Add MCP server tool filtering support to agents-js (#164)

---------
Co-authored-by: Kazuhiro Sera <[email protected]>

Author: vrtnis

.changeset/hungry-suns-search.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents-realtime': patch
+'@openai/agents-core': patch
+---
+
+agents-core, agents-realtime: add MCP tool-filtering support (fixes #162)

docs/src/content/docs/guides/mcp.mdx

@@ -10,6 +10,7 @@ import hostedStreamExample from '../../../../../examples/docs/mcp/hostedStream.t
 import hostedHITLExample from '../../../../../examples/docs/mcp/hostedHITL.ts?raw';
 import streamableHttpExample from '../../../../../examples/docs/mcp/streamableHttp.ts?raw';
 import stdioExample from '../../../../../examples/docs/mcp/stdio.ts?raw';
+import toolFilterExample from '../../../../../examples/docs/mcp/tool-filter.ts?raw';
 
 The [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) is an open protocol that standardizes how applications provide tools and context to LLMs. From the MCP docs:
 
@@ -97,6 +98,16 @@ For **Streamable HTTP** and **Stdio** servers, each time an `Agent` runs it may
 
 Only enable this if you're confident the tool list won't change. To invalidate the cache later, call `invalidateToolsCache()` on the server instance.
 
+### Tool filtering
+
+You can restrict which tools are exposed from each server by passing either a static filter via `createMCPToolStaticFilter` or a custom function. Here’s a combined example showing both approaches:
+
+<Code 
+  lang="typescript" 
+  code={toolFilterExample} 
+  title="Tool filtering" 
+/>
+
 ## Further reading
 
 - [Model Context Protocol](https://modelcontextprotocol.io/) – official specification.

examples/docs/mcp/tool-filter.ts

@@ -0,0 +1,24 @@
+import {
+  MCPServerStdio,
+  MCPServerStreamableHttp,
+  createMCPToolStaticFilter,
+  MCPToolFilterContext,
+} from '@openai/agents';
+
+interface ToolFilterContext {
+  allowAll: boolean;
+}
+
+const server = new MCPServerStdio({
+  fullCommand: 'my-server',
+  toolFilter: createMCPToolStaticFilter({
+    allowed: ['safe_tool'],
+    blocked: ['danger_tool'],
+  }),
+});
+
+const dynamicServer = new MCPServerStreamableHttp({
+  url: 'http://localhost:3000',
+  toolFilter: async ({ runContext }: MCPToolFilterContext, tool) =>
+    (runContext.context as ToolFilterContext).allowAll || tool.name !== 'admin',
+});

examples/mcp/README.md

@@ -12,3 +12,9 @@ Run the example from the repository root:
 ```bash
 pnpm -F mcp start:stdio
 ```
+
+`tool-filter-example.ts` shows how to expose only a subset of server tools:
+
+```bash
+pnpm -F mcp start:tool-filter
+```

examples/mcp/package.json

@@ -12,6 +12,7 @@
     "start:streamable-http": "tsx streamable-http-example.ts",
     "start:hosted-mcp-on-approval": "tsx hosted-mcp-on-approval.ts",
     "start:hosted-mcp-human-in-the-loop": "tsx hosted-mcp-human-in-the-loop.ts",
-    "start:hosted-mcp-simple": "tsx hosted-mcp-simple.ts"
+    "start:hosted-mcp-simple": "tsx hosted-mcp-simple.ts",
+    "start:tool-filter": "tsx tool-filter-example.ts"
   }
 }

examples/mcp/tool-filter-example.ts

@@ -0,0 +1,53 @@
+import {
+  Agent,
+  run,
+  MCPServerStdio,
+  createMCPToolStaticFilter,
+  withTrace,
+} from '@openai/agents';
+import * as path from 'node:path';
+
+async function main() {
+  const samplesDir = path.join(__dirname, 'sample_files');
+  const mcpServer = new MCPServerStdio({
+    name: 'Filesystem Server with filter',
+    fullCommand: `npx -y @modelcontextprotocol/server-filesystem ${samplesDir}`,
+    toolFilter: createMCPToolStaticFilter({
+      allowed: ['read_file', 'list_directory'],
+      blocked: ['write_file'],
+    }),
+  });
+
+  await mcpServer.connect();
+
+  try {
+    await withTrace('MCP Tool Filter Example', async () => {
+      const agent = new Agent({
+        name: 'MCP Assistant',
+        instructions: 'Use the filesystem tools to answer questions.',
+        mcpServers: [mcpServer],
+      });
+
+      console.log('Listing sample files:');
+      let result = await run(
+        agent,
+        'List the files in the sample_files directory.',
+      );
+      console.log(result.finalOutput);
+
+      console.log('\nAttempting to write a file (should be blocked):');
+      result = await run(
+        agent,
+        'Create a file named sample_files/test.txt with the text "hello"',
+      );
+      console.log(result.finalOutput);
+    });
+  } finally {
+    await mcpServer.close();
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package.json

@@ -37,6 +37,7 @@
     "examples:tools-computer-use": "pnpm -F tools start:computer-use",
     "examples:tools-file-search": "pnpm -F tools start:file-search",
     "examples:tools-web-search": "pnpm -F tools start:web-search",
+    "examples:tool-filter": "tsx examples/mcp/tool-filter-example.ts",
     "ci:publish": "pnpm publish -r --no-git-checks",
     "bump-version": "changeset version && pnpm -F @openai/* prebuild",
     "prepare": "husky",

packages/agents-core/src/agent.ts

@@ -531,9 +531,11 @@ export class Agent<
    * Fetches the available tools from the MCP servers.
    * @returns the MCP powered tools
    */
-  async getMcpTools(): Promise<Tool<TContext>[]> {
+  async getMcpTools(
+    runContext: RunContext<TContext>,
+  ): Promise<Tool<TContext>[]> {
     if (this.mcpServers.length > 0) {
-      return getAllMcpTools(this.mcpServers);
+      return getAllMcpTools(this.mcpServers, runContext, this, false);
     }
 
     return [];
@@ -544,8 +546,10 @@ export class Agent<
    *
    * @returns all configured tools
    */
-  async getAllTools(): Promise<Tool<TContext>[]> {
-    return [...(await this.getMcpTools()), ...this.tools];
+  async getAllTools(
+    runContext: RunContext<TContext>,
+  ): Promise<Tool<TContext>[]> {
+    return [...(await this.getMcpTools(runContext)), ...this.tools];
   }
 
   /**

packages/agents-core/src/index.ts

@@ -74,6 +74,12 @@ export {
   MCPServerStdio,
   MCPServerStreamableHttp,
 } from './mcp';
+export {
+  MCPToolFilterCallable,
+  MCPToolFilterContext,
+  MCPToolFilterStatic,
+  createMCPToolStaticFilter,
+} from './mcpUtil';
 export {
   Model,
   ModelProvider,

packages/agents-core/src/mcp.ts

@@ -14,6 +14,9 @@ import {
   JsonObjectSchemaStrict,
   UnknownContext,
 } from './types';
+import type { MCPToolFilterCallable, MCPToolFilterStatic } from './mcpUtil';
+import type { RunContext } from './runContext';
+import type { Agent } from './agent';
 
 export const DEFAULT_STDIO_MCP_CLIENT_LOGGER_NAME =
   'openai-agents:stdio-mcp-client';
@@ -27,6 +30,7 @@ export const DEFAULT_STREAMABLE_HTTP_MCP_CLIENT_LOGGER_NAME =
  */
 export interface MCPServer {
   cacheToolsList: boolean;
+  toolFilter?: MCPToolFilterCallable | MCPToolFilterStatic;
   connect(): Promise<void>;
   readonly name: string;
   close(): Promise<void>;
@@ -41,12 +45,14 @@ export interface MCPServer {
 export abstract class BaseMCPServerStdio implements MCPServer {
   public cacheToolsList: boolean;
   protected _cachedTools: any[] | undefined = undefined;
+  public toolFilter?: MCPToolFilterCallable | MCPToolFilterStatic;
 
   protected logger: Logger;
   constructor(options: MCPServerStdioOptions) {
     this.logger =
       options.logger ?? getLogger(DEFAULT_STDIO_MCP_CLIENT_LOGGER_NAME);
     this.cacheToolsList = options.cacheToolsList ?? false;
+    this.toolFilter = options.toolFilter;
   }
 
   abstract get name(): string;
@@ -74,13 +80,15 @@ export abstract class BaseMCPServerStdio implements MCPServer {
 export abstract class BaseMCPServerStreamableHttp implements MCPServer {
   public cacheToolsList: boolean;
   protected _cachedTools: any[] | undefined = undefined;
+  public toolFilter?: MCPToolFilterCallable | MCPToolFilterStatic;
 
   protected logger: Logger;
   constructor(options: MCPServerStreamableHttpOptions) {
     this.logger =
       options.logger ??
       getLogger(DEFAULT_STREAMABLE_HTTP_MCP_CLIENT_LOGGER_NAME);
     this.cacheToolsList = options.cacheToolsList ?? false;
+    this.toolFilter = options.toolFilter;
   }
 
   abstract get name(): string;
@@ -204,13 +212,17 @@ export class MCPServerStreamableHttp extends BaseMCPServerStreamableHttp {
  */
 export async function getAllMcpFunctionTools<TContext = UnknownContext>(
   mcpServers: MCPServer[],
+  runContext: RunContext<TContext>,
+  agent: Agent<any, any>,
   convertSchemasToStrict = false,
 ): Promise<Tool<TContext>[]> {
   const allTools: Tool<TContext>[] = [];
   const toolNames = new Set<string>();
   for (const server of mcpServers) {
     const serverTools = await getFunctionToolsFromServer(
       server,
+      runContext,
+      agent,
       convertSchemasToStrict,
     );
     const serverToolNames = new Set(serverTools.map((t) => t.name));
@@ -242,6 +254,8 @@ export async function invalidateServerToolsCache(serverName: string) {
  */
 async function getFunctionToolsFromServer<TContext = UnknownContext>(
   server: MCPServer,
+  runContext: RunContext<TContext>,
+  agent: Agent<any, any>,
   convertSchemasToStrict: boolean,
 ): Promise<FunctionTool<TContext, any, unknown>[]> {
   if (server.cacheToolsList && _cachedTools[server.name]) {
@@ -251,7 +265,53 @@ async function getFunctionToolsFromServer<TContext = UnknownContext>(
   }
   return withMCPListToolsSpan(
     async (span) => {
-      const mcpTools = await server.listTools();
+      const fetchedMcpTools = await server.listTools();
+      const mcpTools: MCPTool[] = [];
+      const context = {
+        runContext,
+        agent,
+        serverName: server.name,
+      };
+      for (const tool of fetchedMcpTools) {
+        const filter = server.toolFilter;
+        if (filter) {
+          if (filter && typeof filter === 'function') {
+            const filtered = await filter(context, tool);
+            if (!filtered) {
+              globalLogger.debug(
+                `MCP Tool (server: ${server.name}, tool: ${tool.name}) is blocked by the callable filter.`,
+              );
+              continue; // skip this tool
+            }
+          } else {
+            const allowedToolNames = filter.allowedToolNames ?? [];
+            const blockedToolNames = filter.blockedToolNames ?? [];
+            if (allowedToolNames.length > 0 || blockedToolNames.length > 0) {
+              const allowed =
+                allowedToolNames.length > 0
+                  ? allowedToolNames.includes(tool.name)
+                  : true;
+              const blocked =
+                blockedToolNames.length > 0
+                  ? blockedToolNames.includes(tool.name)
+                  : false;
+              if (!allowed || blocked) {
+                if (blocked) {
+                  globalLogger.debug(
+                    `MCP Tool (server: ${server.name}, tool: ${tool.name}) is blocked by the static filter.`,
+                  );
+                } else if (!allowed) {
+                  globalLogger.debug(
+                    `MCP Tool (server: ${server.name}, tool: ${tool.name}) is not allowed by the static filter.`,
+                  );
+                }
+                continue; // skip this tool
+              }
+            }
+          }
+        }
+        mcpTools.push(tool);
+      }
       span.spanData.result = mcpTools.map((t) => t.name);
       const tools: FunctionTool<TContext, any, string>[] = mcpTools.map((t) =>
         mcpToFunctionTool(t, server, convertSchemasToStrict),
@@ -270,9 +330,16 @@ async function getFunctionToolsFromServer<TContext = UnknownContext>(
  */
 export async function getAllMcpTools<TContext = UnknownContext>(
   mcpServers: MCPServer[],
+  runContext: RunContext<TContext>,
+  agent: Agent<TContext, any>,
   convertSchemasToStrict = false,
 ): Promise<Tool<TContext>[]> {
-  return getAllMcpFunctionTools(mcpServers, convertSchemasToStrict);
+  return getAllMcpFunctionTools(
+    mcpServers,
+    runContext,
+    agent,
+    convertSchemasToStrict,
+  );
 }
 
 /**
@@ -363,6 +430,7 @@ export interface BaseMCPServerStdioOptions {
   encoding?: string;
   encodingErrorHandler?: 'strict' | 'ignore' | 'replace';
   logger?: Logger;
+  toolFilter?: MCPToolFilterCallable | MCPToolFilterStatic;
 }
 export interface DefaultMCPServerStdioOptions
   extends BaseMCPServerStdioOptions {
@@ -383,6 +451,7 @@ export interface MCPServerStreamableHttpOptions {
   clientSessionTimeoutSeconds?: number;
   name?: string;
   logger?: Logger;
+  toolFilter?: MCPToolFilterCallable | MCPToolFilterStatic;
 
   // ----------------------------------------------------
   // OAuth