docs(mcp): document tool filtering

vrtnis · vrtnis · commit 48ebb1cdc3b5 · 2025-07-27T23:34:10.000-07:00
diff --git a/docs/src/content/docs/guides/mcp.mdx b/docs/src/content/docs/guides/mcp.mdx
@@ -97,6 +97,23 @@ 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. Pass either a static filter
+using `createStaticToolFilter` or a custom function:
+
+```ts
+const server = new MCPServerStdio({
+  fullCommand: 'my-server',
+  toolFilter: createStaticToolFilter(['safe_tool'], ['danger_tool']),
+});
+
+const dynamicServer = new MCPServerStreamableHttp({
+  url: 'http://localhost:3000',
+  toolFilter: ({ runContext }, tool) => runContext.context.allowAll || tool.name !== 'admin',
+});
+```
+
 ## Further reading
 
 - [Model Context Protocol](https://modelcontextprotocol.io/) – official specification.
diff --git a/packages/agents-core/src/agent.ts b/packages/agents-core/src/agent.ts
@@ -514,9 +514,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, false, runContext, this);
     }
 
     return [];
@@ -527,8 +529,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];
   }
 
   /**
diff --git a/packages/agents-core/src/index.ts b/packages/agents-core/src/index.ts
@@ -74,6 +74,12 @@ export {
   MCPServerStdio,
   MCPServerStreamableHttp,
 } from './mcp';
+export {
+  ToolFilterCallable,
+  ToolFilterContext,
+  ToolFilterStatic,
+  createStaticToolFilter,
+} from './mcpUtil';
 export {
   Model,
   ModelProvider,
diff --git a/packages/agents-core/src/mcp.ts b/packages/agents-core/src/mcp.ts
@@ -14,6 +14,9 @@ import {
   JsonObjectSchemaStrict,
   UnknownContext,
 } from './types';
+import type { ToolFilterCallable, ToolFilterStatic } 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';
@@ -30,7 +33,10 @@ export interface MCPServer {
   connect(): Promise<void>;
   readonly name: string;
   close(): Promise<void>;
-  listTools(): Promise<MCPTool[]>;
+  listTools(
+    runContext?: RunContext<any>,
+    agent?: Agent<any, any>,
+  ): Promise<MCPTool[]>;
   callTool(
     toolName: string,
     args: Record<string, unknown> | null,
@@ -41,18 +47,23 @@ export interface MCPServer {
 export abstract class BaseMCPServerStdio implements MCPServer {
   public cacheToolsList: boolean;
   protected _cachedTools: any[] | undefined = undefined;
+  protected toolFilter?: ToolFilterCallable | ToolFilterStatic;
 
   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;
   abstract connect(): Promise<void>;
   abstract close(): Promise<void>;
-  abstract listTools(): Promise<any[]>;
+  abstract listTools(
+    runContext?: RunContext<any>,
+    agent?: Agent<any, any>,
+  ): Promise<any[]>;
   abstract callTool(
     _toolName: string,
     _args: Record<string, unknown> | null,
@@ -74,19 +85,24 @@ export abstract class BaseMCPServerStdio implements MCPServer {
 export abstract class BaseMCPServerStreamableHttp implements MCPServer {
   public cacheToolsList: boolean;
   protected _cachedTools: any[] | undefined = undefined;
+  protected toolFilter?: ToolFilterCallable | ToolFilterStatic;
 
   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;
   abstract connect(): Promise<void>;
   abstract close(): Promise<void>;
-  abstract listTools(): Promise<any[]>;
+  abstract listTools(
+    runContext?: RunContext<any>,
+    agent?: Agent<any, any>,
+  ): Promise<any[]>;
   abstract callTool(
     _toolName: string,
     _args: Record<string, unknown> | null,
@@ -141,11 +157,14 @@ export class MCPServerStdio extends BaseMCPServerStdio {
   close(): Promise<void> {
     return this.underlying.close();
   }
-  async listTools(): Promise<MCPTool[]> {
+  async listTools(
+    runContext?: RunContext<any>,
+    agent?: Agent<any, any>,
+  ): Promise<MCPTool[]> {
     if (this.cacheToolsList && this._cachedTools) {
       return this._cachedTools;
     }
-    const tools = await this.underlying.listTools();
+    const tools = await this.underlying.listTools(runContext, agent);
     if (this.cacheToolsList) {
       this._cachedTools = tools;
     }
@@ -177,11 +196,14 @@ export class MCPServerStreamableHttp extends BaseMCPServerStreamableHttp {
   close(): Promise<void> {
     return this.underlying.close();
   }
-  async listTools(): Promise<MCPTool[]> {
+  async listTools(
+    runContext?: RunContext<any>,
+    agent?: Agent<any, any>,
+  ): Promise<MCPTool[]> {
     if (this.cacheToolsList && this._cachedTools) {
       return this._cachedTools;
     }
-    const tools = await this.underlying.listTools();
+    const tools = await this.underlying.listTools(runContext, agent);
     if (this.cacheToolsList) {
       this._cachedTools = tools;
     }
@@ -205,13 +227,17 @@ export class MCPServerStreamableHttp extends BaseMCPServerStreamableHttp {
 export async function getAllMcpFunctionTools<TContext = UnknownContext>(
   mcpServers: MCPServer[],
   convertSchemasToStrict = false,
+  runContext?: RunContext<TContext>,
+  agent?: Agent<TContext, any>,
 ): Promise<Tool<TContext>[]> {
   const allTools: Tool<TContext>[] = [];
   const toolNames = new Set<string>();
   for (const server of mcpServers) {
     const serverTools = await getFunctionToolsFromServer(
       server,
       convertSchemasToStrict,
+      runContext,
+      agent,
     );
     const serverToolNames = new Set(serverTools.map((t) => t.name));
     const intersection = [...serverToolNames].filter((n) => toolNames.has(n));
@@ -243,6 +269,8 @@ export async function invalidateServerToolsCache(serverName: string) {
 async function getFunctionToolsFromServer<TContext = UnknownContext>(
   server: MCPServer,
   convertSchemasToStrict: boolean,
+  runContext?: RunContext<TContext>,
+  agent?: Agent<TContext, any>,
 ): Promise<FunctionTool<TContext, any, unknown>[]> {
   if (server.cacheToolsList && _cachedTools[server.name]) {
     return _cachedTools[server.name].map((t) =>
@@ -251,7 +279,7 @@ async function getFunctionToolsFromServer<TContext = UnknownContext>(
   }
   return withMCPListToolsSpan(
     async (span) => {
-      const mcpTools = await server.listTools();
+      const mcpTools = await server.listTools(runContext, agent);
       span.spanData.result = mcpTools.map((t) => t.name);
       const tools: FunctionTool<TContext, any, string>[] = mcpTools.map((t) =>
         mcpToFunctionTool(t, server, convertSchemasToStrict),
@@ -271,8 +299,15 @@ async function getFunctionToolsFromServer<TContext = UnknownContext>(
 export async function getAllMcpTools<TContext = UnknownContext>(
   mcpServers: MCPServer[],
   convertSchemasToStrict = false,
+  runContext?: RunContext<TContext>,
+  agent?: Agent<TContext, any>,
 ): Promise<Tool<TContext>[]> {
-  return getAllMcpFunctionTools(mcpServers, convertSchemasToStrict);
+  return getAllMcpFunctionTools(
+    mcpServers,
+    convertSchemasToStrict,
+    runContext,
+    agent,
+  );
 }
 
 /**
@@ -363,6 +398,7 @@ export interface BaseMCPServerStdioOptions {
   encoding?: string;
   encodingErrorHandler?: 'strict' | 'ignore' | 'replace';
   logger?: Logger;
+  toolFilter?: ToolFilterCallable | ToolFilterStatic;
 }
 export interface DefaultMCPServerStdioOptions
   extends BaseMCPServerStdioOptions {
@@ -383,6 +419,7 @@ export interface MCPServerStreamableHttpOptions {
   clientSessionTimeoutSeconds?: number;
   name?: string;
   logger?: Logger;
+  toolFilter?: ToolFilterCallable | ToolFilterStatic;
 
   // ----------------------------------------------------
   // OAuth
diff --git a/packages/agents-core/src/mcpUtil.ts b/packages/agents-core/src/mcpUtil.ts
@@ -0,0 +1,46 @@
+import type { Agent } from './agent';
+import type { RunContext } from './runContext';
+import type { MCPTool } from './mcp';
+import type { UnknownContext } from './types';
+
+/** Context information available to tool filter functions. */
+export interface ToolFilterContext<TContext = UnknownContext> {
+  /** The current run context. */
+  runContext: RunContext<TContext>;
+  /** The agent requesting the tools. */
+  agent: Agent<TContext, any>;
+  /** Name of the MCP server providing the tools. */
+  serverName: string;
+}
+
+/** A function that determines whether a tool should be available. */
+export type ToolFilterCallable<TContext = UnknownContext> = (
+  context: ToolFilterContext<TContext>,
+  tool: MCPTool,
+) => boolean | Promise<boolean>;
+
+/** Static tool filter configuration using allow and block lists. */
+export interface ToolFilterStatic {
+  /** Optional list of tool names to allow. */
+  allowedToolNames?: string[];
+  /** Optional list of tool names to block. */
+  blockedToolNames?: string[];
+}
+
+/** Convenience helper to create a static tool filter. */
+export function createStaticToolFilter(
+  allowedToolNames?: string[],
+  blockedToolNames?: string[],
+): ToolFilterStatic | undefined {
+  if (!allowedToolNames && !blockedToolNames) {
+    return undefined;
+  }
+  const filter: ToolFilterStatic = {};
+  if (allowedToolNames) {
+    filter.allowedToolNames = allowedToolNames;
+  }
+  if (blockedToolNames) {
+    filter.blockedToolNames = blockedToolNames;
+  }
+  return filter;
+}
diff --git a/packages/agents-core/src/run.ts b/packages/agents-core/src/run.ts
@@ -322,7 +322,7 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
               setCurrentSpan(state._currentAgentSpan);
             }
 
-            const tools = await state._currentAgent.getAllTools();
+            const tools = await state._currentAgent.getAllTools(state._context);
             const serializedTools = tools.map((t) => serializeTool(t));
             const serializedHandoffs = handoffs.map((h) => serializeHandoff(h));
             if (state._currentAgentSpan) {
@@ -615,7 +615,7 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
       while (true) {
         const currentAgent = result.state._currentAgent;
         const handoffs = currentAgent.handoffs.map(getHandoff);
-        const tools = await currentAgent.getAllTools();
+        const tools = await currentAgent.getAllTools(result.state._context);
         const serializedTools = tools.map((t) => serializeTool(t));
         const serializedHandoffs = handoffs.map((h) => serializeHandoff(h));
 
diff --git a/packages/agents-core/src/runState.ts b/packages/agents-core/src/runState.ts
@@ -558,6 +558,7 @@ export class RunState<TContext, TAgent extends Agent<any, any>> {
           agentMap,
           state._currentAgent,
           stateJson.lastProcessedResponse,
+          state._context,
         )
       : undefined;
 
@@ -710,8 +711,9 @@ async function deserializeProcessedResponse<TContext = UnknownContext>(
   serializedProcessedResponse: z.infer<
     typeof serializedProcessedResponseSchema
   >,
+  runContext: RunContext<TContext>,
 ): Promise<ProcessedResponse<TContext>> {
-  const allTools = await currentAgent.getAllTools();
+  const allTools = await currentAgent.getAllTools(runContext);
   const tools = new Map(
     allTools
       .filter((tool) => tool.type === 'function')
diff --git a/packages/agents-core/src/shims/mcp-server/browser.ts b/packages/agents-core/src/shims/mcp-server/browser.ts
@@ -6,6 +6,8 @@ import {
   MCPServerStreamableHttpOptions,
   MCPTool,
 } from '../../mcp';
+import type { RunContext } from '../../runContext';
+import type { Agent } from '../../agent';
 
 export class MCPServerStdio extends BaseMCPServerStdio {
   constructor(params: MCPServerStdioOptions) {
@@ -20,7 +22,10 @@ export class MCPServerStdio extends BaseMCPServerStdio {
   close(): Promise<void> {
     throw new Error('Method not implemented.');
   }
-  listTools(): Promise<MCPTool[]> {
+  listTools(
+    _runContext?: RunContext<any>,
+    _agent?: Agent<any, any>,
+  ): Promise<MCPTool[]> {
     throw new Error('Method not implemented.');
   }
   callTool(
@@ -47,7 +52,10 @@ export class MCPServerStreamableHttp extends BaseMCPServerStreamableHttp {
   close(): Promise<void> {
     throw new Error('Method not implemented.');
   }
-  listTools(): Promise<MCPTool[]> {
+  listTools(
+    _runContext?: RunContext<any>,
+    _agent?: Agent<any, any>,
+  ): Promise<MCPTool[]> {
     throw new Error('Method not implemented.');
   }
   callTool(
diff --git a/packages/agents-core/src/shims/mcp-server/node.ts b/packages/agents-core/src/shims/mcp-server/node.ts
diff --git a/packages/agents-core/test/mcpToolFilter.test.ts b/packages/agents-core/test/mcpToolFilter.test.ts
diff --git a/packages/agents-realtime/src/realtimeSession.ts b/packages/agents-realtime/src/realtimeSession.ts
