feat: add getAllMcpTools function with example and overloads [AI]

Author: xierenyuan

examples/mcp/README.md

@@ -18,3 +18,9 @@ pnpm -F mcp start:stdio
 ```bash
 pnpm -F mcp start:tool-filter
 ```
+
+`get-all-mcp-tools-example.ts` demonstrates how to use the `getAllMcpTools` function to fetch tools from multiple MCP servers:
+
+```bash
+pnpm -F mcp start:get-all-tools
+```

examples/mcp/get-all-mcp-tools-example.ts

@@ -0,0 +1,120 @@
+import {
+  Agent,
+  run,
+  MCPServerStdio,
+  getAllMcpTools,
+  withTrace,
+} from '@openai/agents';
+import * as path from 'node:path';
+import { createOpenAI } from '@ai-sdk/openai';
+import { aisdk } from '@openai/agents-extensions';
+
+const openai = createOpenAI({
+  baseURL: 'https://api.moonshot.cn/v1',
+  apiKey: process.env.MOONSHOT_API_KEY,
+});
+
+const model = aisdk(openai('kimi-k2-turbo-preview'));
+
+async function main() {
+  const samplesDir = path.join(__dirname, 'sample_files');
+
+  // Create multiple MCP servers to demonstrate getAllMcpTools
+  const filesystemServer = new MCPServerStdio({
+    name: 'Filesystem Server',
+    fullCommand: `npx -y @modelcontextprotocol/server-filesystem ${samplesDir}`,
+  });
+
+  // Note: This example shows how to use multiple servers
+  // In practice, you would have different servers with different tools
+  const servers = [filesystemServer];
+
+  // Connect all servers
+  for (const server of servers) {
+    await server.connect();
+  }
+
+  try {
+    await withTrace('getAllMcpTools Example', async () => {
+      console.log('=== Using getAllMcpTools to fetch all tools ===\n');
+
+      // Method 1: Simple array of servers
+      const allTools = await getAllMcpTools(servers);
+      console.log(
+        `Found ${allTools.length} tools from ${servers.length} server(s):`,
+      );
+      allTools.forEach((tool) => {
+        const description =
+          tool.type === 'function' ? tool.description : 'No description';
+        console.log(`- ${tool.name}: ${description}`);
+      });
+
+      console.log('\n=== Using getAllMcpTools with options object ===\n');
+
+      // Method 2: Using options object (recommended for more control)
+      const allToolsWithOptions = await getAllMcpTools({
+        mcpServers: servers,
+        convertSchemasToStrict: true, // Convert schemas to strict mode
+      });
+
+      console.log(
+        `Found ${allToolsWithOptions.length} tools with strict schemas:`,
+      );
+      allToolsWithOptions.forEach((tool) => {
+        const description =
+          tool.type === 'function' ? tool.description : 'No description';
+        console.log(`- ${tool.name}: ${description}`);
+      });
+
+      console.log('\n=== Creating agent with pre-fetched tools ===\n');
+
+      // Create agent using the pre-fetched tools
+      const agent = new Agent({
+        name: 'MCP Assistant with Pre-fetched Tools',
+        instructions:
+          'Use the available tools to help the user with file operations.',
+        tools: allTools, // Use pre-fetched tools instead of mcpServers
+        model,
+      });
+
+      // Test the agent
+      const message = 'List the available files and read one of them.';
+      console.log(`Running: ${message}\n`);
+      const result = await run(agent, message);
+      console.log(result.finalOutput);
+
+      console.log(
+        '\n=== Demonstrating tool filtering with getAllMcpTools ===\n',
+      );
+
+      // Add tool filter to one of the servers
+      filesystemServer.toolFilter = {
+        allowedToolNames: ['read_file'], // Only allow read_file tool
+      };
+
+      // Note: For callable filters to work, you need to pass runContext and agent
+      // This is typically done internally when the agent runs
+      const filteredTools = await getAllMcpTools({
+        mcpServers: servers,
+        convertSchemasToStrict: false,
+        // runContext and agent would normally be provided by the agent runtime
+        // For demo purposes, we're showing the structure
+      });
+
+      console.log(`After filtering, found ${filteredTools.length} tools:`);
+      filteredTools.forEach((tool) => {
+        console.log(`- ${tool.name}`);
+      });
+    });
+  } finally {
+    // Clean up - close all servers
+    for (const server of servers) {
+      await server.close();
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

examples/mcp/package.json

@@ -4,7 +4,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "@openai/agents": "workspace:*",
-    "zod": "3.25.40 - 3.25.67"
+    "zod": "3.25.40 - 3.25.67",
+    "@openai/agents-extensions": "workspace:*",
+    "@ai-sdk/openai": "^1.1.3"
   },
   "scripts": {
     "build-check": "tsc --noEmit",
@@ -14,6 +16,7 @@
     "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:tool-filter": "tsx tool-filter-example.ts",
-    "start:sse": "tsx sse-example.ts"
+    "start:sse": "tsx sse-example.ts",
+    "start:get-all-tools": "tsx get-all-mcp-tools-example.ts"
   }
 }

packages/agents-core/src/mcp.ts

@@ -392,21 +392,42 @@ export type GetAllMcpToolsOptions<TContext> = {
  * Returns all MCP tools from the provided servers, using the function tool conversion.
  * If runContext and agent are provided, callable tool filters will be applied.
  */
-export async function getAllMcpTools<TContext = UnknownContext>({
-  mcpServers,
+export async function getAllMcpTools<TContext = UnknownContext>(
+  mcpServers: MCPServer[],
+): Promise<Tool<TContext>[]>;
+export async function getAllMcpTools<TContext = UnknownContext>(
+  opts: GetAllMcpToolsOptions<TContext>,
+): Promise<Tool<TContext>[]>;
+export async function getAllMcpTools<TContext = UnknownContext>(
+  mcpServersOrOpts: MCPServer[] | GetAllMcpToolsOptions<TContext>,
+  runContext?: RunContext<TContext>,
+  agent?: Agent<TContext, any>,
   convertSchemasToStrict = false,
-  runContext,
-  agent,
-}: GetAllMcpToolsOptions<TContext>): Promise<Tool<TContext>[]> {
+): Promise<Tool<TContext>[]> {
+  const opts = Array.isArray(mcpServersOrOpts)
+    ? {
+        mcpServers: mcpServersOrOpts,
+        runContext,
+        agent,
+        convertSchemasToStrict,
+      }
+    : mcpServersOrOpts;
+
+  const {
+    mcpServers,
+    convertSchemasToStrict: convertSchemasToStrictFromOpts = false,
+    runContext: runContextFromOpts,
+    agent: agentFromOpts,
+  } = opts;
   const allTools: Tool<TContext>[] = [];
   const toolNames = new Set<string>();
 
   for (const server of mcpServers) {
     const serverTools = await getFunctionToolsFromServer({
       server,
-      convertSchemasToStrict,
-      runContext,
-      agent,
+      convertSchemasToStrict: convertSchemasToStrictFromOpts,
+      runContext: runContextFromOpts,
+      agent: agentFromOpts,
     });
     const serverToolNames = new Set(serverTools.map((t) => t.name));
     const intersection = [...serverToolNames].filter((n) => toolNames.has(n));