feat(ai): allow custom mcp transports (#5209)

Author: iteratetograceness

.changeset/cold-apples-design.md

@@ -0,0 +1,7 @@
+---
+'next-openai': patch
+'ai': patch
+---
+
+feat: enable custom mcp transports
+breaking change: remove internal stdio transport creation

content/cookbook/05-node/54-mcp-tools.mdx

@@ -10,18 +10,21 @@ The AI SDK supports Model Context Protocol (MCP) tools by offering a lightweight
 
 ```ts
 import { experimental_createMCPClient, generateText } from 'ai';
+import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';
 import { openai } from '@ai-sdk/openai';
 
 let clientOne;
 let clientTwo;
+let clientThree;
 
 try {
   // Initialize an MCP client to connect to a `stdio` MCP server:
+  const transport = new Experimental_StdioMCPTransport({
+    command: 'node',
+    args: ['src/stdio/dist/server.js'],
+  });
   clientOne = await experimental_createMCPClient({
-    transport: {
-      type: 'stdio',
-      command: 'node server.js',
-    },
+    transport,
   });
 
   // Alternatively, you can connect to a Server-Sent Events (SSE) MCP server:
@@ -32,12 +35,21 @@ try {
     },
   });
 
+  // Similarly to the stdio example, you can pass in your own custom transport as long as it implements the `MCPTransport` interface:
+  const transport = new MyCustomTransport({
+    // ...
+  });
+  clientThree = await experimental_createMCPClient({
+    transport,
+  });
+
   const toolSetOne = await clientOne.tools();
   const toolSetTwo = await clientTwo.tools();
-
+  const toolSetThree = await clientThree.tools();
   const tools = {
     ...toolSetOne,
-    ...toolSetTwo, // note: this overrides tools from toolSetOne when there are naming collisions
+    ...toolSetTwo,
+    ...toolSetThree, // note: this approach causes subsequent tool sets to override tools with the same name
   };
 
   const response = await generateText({

content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

@@ -639,15 +639,18 @@ Create an MCP client using either:
 
 - `stdio`: Uses standard input and output streams for communication, ideal for local tool servers running on the same machine (like CLI tools or local services)
 - `SSE` (Server-Sent Events): Uses HTTP-based real-time communication, better suited for remote servers that need to send data over the network
+- Custom transport: Bring your own transport by implementing the `MCPTransport` interface
 
 ```typescript
+import { experimental_createMCPClient as createMCPClient } from 'ai';
+import { Experimental_StdioMCPTransport as StdioMCPTransport } from 'ai/mcp-stdio';
+
 // Example of using MCP with stdio
 const mcpClient = await createMCPClient({
-  transport: {
-    type: 'stdio',
+  transport: new StdioMCPTransport({
     command: 'node',
     args: ['src/stdio/dist/server.js'],
-  },
+  }),
 });
 
 // Example of using MCP with SSE
@@ -657,17 +660,25 @@ const mcpClient = await createMCPClient({
     url: 'https://my-server.com/sse',
   },
 });
+
+// Example of using a custom transport
+const transport = new MyCustomTransport({
+  // ...
+});
+const mcpClient = await createMCPClient({
+  transport,
+});
 ```
 
 After initialization, always close the MCP client when you're done to prevent resource leaks. Use try/finally or cleanup functions in your framework:
 
 ```typescript
   try {
-    const mcpClient = await createMCPClient({...});
+    const mcpClient = await experimental_createMCPClient({...});
     const tools = await mcpClient.tools();
     // use tools...
   } finally {
-    await client?.close();
+    await mcpClient?.close();
   }
 ```
 

content/docs/07-reference/01-ai-sdk-core/21-create-mcp-client.mdx

@@ -34,47 +34,47 @@ This feature is experimental and may change or be removed in the future.
           parameters: [
             {
               name: 'transport',
-              type: 'TransportConfig = McpStdioServerConfig | McpSSEServerConfig',
+              type: 'TransportConfig = MCPTransport | McpSSEServerConfig',
               description: 'Configuration for the message transport layer.',
               properties: [
                 {
-                  type: 'McpStdioServerConfig',
+                  type: 'MCPTransport',
+                  description:
+                    'A client transport instance, used explicitly for stdio or custom transports',
                   parameters: [
                     {
-                      name: 'type',
-                      type: "'stdio'",
-                      description:
-                        'Use standard input/output streams for communication',
+                      name: 'start',
+                      type: '() => Promise<void>',
+                      description: 'A method that starts the transport',
                     },
                     {
-                      name: 'command',
-                      type: 'string',
-                      description: 'Command to start the server',
+                      name: 'send',
+                      type: '(message: JSONRPCMessage) => Promise<void>',
+                      description:
+                        'A method that sends a message through the transport',
                     },
                     {
-                      name: 'args',
-                      type: 'string[]',
-                      isOptional: true,
-                      description: 'Command line arguments',
+                      name: 'close',
+                      type: '() => Promise<void>',
+                      description: 'A method that closes the transport',
                     },
                     {
-                      name: 'env',
-                      type: 'Record<string, string>',
-                      isOptional: true,
-                      description: 'Environment variables',
+                      name: 'onclose',
+                      type: '() => void',
+                      description:
+                        'A method that is called when the transport is closed',
                     },
                     {
-                      name: 'cwd',
-                      type: 'string',
-                      isOptional: true,
-                      description: 'Working directory for the server process',
+                      name: 'onerror',
+                      type: '(error: Error) => void',
+                      description:
+                        'A method that is called when the transport encounters an error',
                     },
                     {
-                      name: 'stderr',
-                      type: 'IOType | Stream | number',
-                      isOptional: true,
+                      name: 'onmessage',
+                      type: '(message: JSONRPCMessage) => void',
                       description:
-                        'Handler for stderr output. Defaults to "inherit".',
+                        'A method that is called when the transport receives a message',
                     },
                   ],
                 },

content/docs/07-reference/01-ai-sdk-core/22-mcp-stdio-transport.mdx

@@ -0,0 +1,68 @@
+---
+title: Experimental_StdioMCPTransport
+description: Create a transport for Model Context Protocol (MCP) clients to communicate with MCP servers using standard input and output streams
+---
+
+# `Experimental_StdioMCPTransport`
+
+Creates a transport for Model Context Protocol (MCP) clients to communicate with MCP servers using standard input and output streams. This transport is only supported in Node.js environments.
+
+This feature is experimental and may change or be removed in the future.
+
+## Import
+
+<Snippet
+  text={`import { Experimental_StdioMCPTransport } from "ai/mcp-stdio"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'config',
+      type: 'StdioConfig',
+      description: 'Configuration for the MCP client.',
+      properties: [
+        {
+          type: 'StdioConfig',
+          parameters: [
+            {
+              name: 'command',
+              type: 'string',
+              description: 'The command to run the MCP server.',
+            },
+            {
+              name: 'args',
+              type: 'string[]',
+              isOptional: true,
+              description: 'The arguments to pass to the MCP server.',
+            },
+            {
+              name: 'env',
+              type: 'Record<string, string>',
+              isOptional: true,
+              description:
+                'The environment variables to set for the MCP server.',
+            },
+            {
+              name: 'stderr',
+              type: 'IOType | Stream | number',
+              isOptional: true,
+              description: "The stream to write the MCP server's stderr to.",
+            },
+            {
+              name: 'cwd',
+              type: 'string',
+              isOptional: true,
+              description: 'The current working directory for the MCP server.',
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>

examples/mcp/package.json

@@ -7,6 +7,8 @@
     "sse:client": "tsx src/sse/client.ts",
     "stdio:build": "tsc src/stdio/server.ts --outDir src/stdio/dist --target es2023 --module nodenext",
     "stdio:client": "tsx src/stdio/client.ts",
+    "custom-transport:build": "tsc src/custom-transport/server.ts --outDir src/custom-transport/dist --target es2023 --module nodenext",
+    "custom-transport:client": "tsx src/custom-transport/client.ts",
     "type-check": "tsc --noEmit"
   },
   "dependencies": {

examples/mcp/src/stdio/client.ts

@@ -1,18 +1,23 @@
 import { openai } from '@ai-sdk/openai';
 import { experimental_createMCPClient, generateText } from 'ai';
+// import { StdioClientTransport } from 'ai/mcp-stdio';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import 'dotenv/config';
 import { z } from 'zod';
 
 async function main() {
   let mcpClient;
 
   try {
+    // Or use the AI SDK's stdio transport by importing:
+    // import { StdioClientTransport } from 'ai/mcp-stdio';
+    const stdioTransport = new StdioClientTransport({
+      command: 'node',
+      args: ['src/stdio/dist/server.js'],
+    });
+
     mcpClient = await experimental_createMCPClient({
-      transport: {
-        type: 'stdio',
-        command: 'node',
-        args: ['src/stdio/dist/server.js'],
-      },
+      transport: stdioTransport,
     });
 
     const { text: answer } = await generateText({

examples/mcp/src/stdio/server.ts

@@ -44,7 +44,7 @@ server.tool(
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error('Pokemon MCP Server running on stdio');
+  console.log('Pokemon MCP Server running on stdio');
 }
 
 main().catch(error => {

examples/next-openai/app/api/mcp/route.ts

@@ -0,0 +1,35 @@
+import { openai } from '@ai-sdk/openai';
+import { experimental_createMCPClient, generateText } from 'ai';
+
+export async function POST() {
+  let client;
+
+  try {
+    client = await experimental_createMCPClient({
+      transport: {
+        type: 'sse',
+        url: 'http://localhost:8080/sse',
+      },
+    });
+
+    const tools = await client.tools();
+
+    const { text } = await generateText({
+      model: openai('gpt-4o-mini', { structuredOutputs: true }),
+      tools,
+      maxSteps: 10,
+      onStepFinish: async ({ toolResults }) => {
+        console.log(`STEP RESULTS: ${JSON.stringify(toolResults, null, 2)}`);
+      },
+      system: 'You are a helpful chatbot',
+      prompt: 'Can you find a product called The Product?',
+    });
+
+    return Response.json({ text });
+  } catch (error) {
+    console.error(error);
+    return Response.json({ error: 'Failed to generate text' });
+  } finally {
+    await client?.close();
+  }
+}

examples/next-openai/app/mcp/page.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+import { useState } from 'react';
+
+export default function Page() {
+  const [response, setResponse] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const handleClick = async () => {
+    setIsLoading(true);
+    const response = await fetch('/api/mcp', {
+      method: 'POST',
+      body: JSON.stringify({
+        prompt: 'Can you find a product called The Product?',
+      }),
+    });
+    const data = await response.json();
+    setResponse(data.text);
+    setIsLoading(false);
+  };
+
+  return (
+    <div className="flex flex-col items-center justify-center h-screen gap-4">
+      <button
+        className="bg-blue-500 text-white p-2 rounded-md"
+        onClick={handleClick}
+        disabled={isLoading}
+      >
+        {isLoading ? 'Searching...' : 'Find Product'}
+      </button>
+      {response && <p>Result: {response}</p>}
+    </div>
+  );
+}

packages/ai/core/tool/index.ts

@@ -1,3 +1,4 @@
 export { createMCPClient as experimental_createMCPClient } from './mcp/mcp-client';
+export type { MCPTransport } from './mcp/mcp-transport';
 export { tool } from './tool';
 export type { CoreTool, Tool, ToolExecutionOptions } from './tool';