chore (docs): update MCP examples (vercel#5373)

Author: iteratetograceness

content/cookbook/01-next/73-mcp-tools.mdx

@@ -0,0 +1,107 @@
+---
+title: Model Context Protocol (MCP) Tools
+description: Learn how to use MCP tools with the AI SDK and Next.js
+tags: ['next', 'tool use', 'agent', 'mcp']
+---
+
+# MCP Tools
+
+The AI SDK supports Model Context Protocol (MCP) tools by offering a lightweight client that exposes a `tools` method for retrieving tools from a MCP server. After use, the client should always be closed to release resources.
+
+## Server
+
+Let's create a route handler for `/api/completion` that will generate text based on the input prompt and MCP tools that can be called at any time during a generation. The route will call the `streamText` function from the `ai` module, which will then generate text based on the input prompt and stream it to the client.
+
+```ts filename="app/api/completion/route.ts"
+import { experimental_createMCPClient, streamText } from 'ai';
+import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';
+import { openai } from '@ai-sdk/openai';
+
+export async function POST(req: Request) {
+  const { prompt }: { prompt: string } = await req.json();
+
+  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'],
+    });
+    const stdioClient = await experimental_createMCPClient({
+      transport,
+    });
+
+    // Alternatively, you can connect to a Server-Sent Events (SSE) MCP server:
+    const sseClient = await experimental_createMCPClient({
+      transport: {
+        type: 'sse',
+        url: 'https://actions.zapier.com/mcp/[YOUR_KEY]/sse',
+      },
+    });
+
+    // 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({
+      // ...
+    });
+    const customTransportClient = await experimental_createMCPClient({
+      transport,
+    });
+
+    const toolSetOne = await stdioClient.tools();
+    const toolSetTwo = await sseClient.tools();
+    const toolSetThree = await customTransportClient.tools();
+    const tools = {
+      ...toolSetOne,
+      ...toolSetTwo,
+      ...toolSetThree, // note: this approach causes subsequent tool sets to override tools with the same name
+    };
+
+    const response = await streamText({
+      model: openai('gpt-4o'),
+      tools,
+      prompt,
+      // When streaming, the client should be closed after the response is finished:
+      onFinish: async () => {
+        await stdioClient.close();
+        await sseClient.close();
+        await customTransportClient.close();
+      },
+    });
+
+    return response.toDataStreamResponse();
+  } catch (error) {
+    return new Response('Internal Server Error', { status: 500 });
+  }
+}
+```
+
+## Client
+
+Let's create a simple React component that imports the `useCompletion` hook from the `@ai-sdk/react` module. The `useCompletion` hook will call the `/api/completion` endpoint when a button is clicked. The endpoint will generate text based on the input prompt and stream it to the client.
+
+```tsx filename="app/page.tsx"
+'use client';
+
+import { useCompletion } from '@ai-sdk/react';
+
+export default function Page() {
+  const { completion, complete } = useCompletion({
+    api: '/api/completion',
+  });
+
+  return (
+    <div>
+      <div
+        onClick={async () => {
+          await complete(
+            'Please schedule a call with Sonny and Robby for tomorrow at 10am ET for me!',
+          );
+        }}
+      >
+        Schedule a call
+      </div>
+
+      {completion}
+    </div>
+  );
+}
+```

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

@@ -693,15 +693,37 @@ const mcpClient = await createMCPClient({
 
 #### Closing the MCP Client
 
-After initialization, always close the MCP client when you're done to prevent resource leaks. Use try/finally or cleanup functions in your framework:
+After initialization, you should close the MCP client based on your usage pattern:
+
+- For short-lived usage (e.g., single requests), close the client when the response is finished
+- For long-running clients (e.g., command line apps), keep the client open but ensure it's closed when the application terminates
+
+When streaming responses, you can close the client when the LLM response has finished. For example, when using `streamText`, you should use the `onFinish` callback:
+
+```typescript
+const mcpClient = await experimental_createMCPClient({
+  // ...
+});
+
+const result = await streamText({
+  model: openai('gpt-4o'),
+  tools: mcpClient.tools(),
+  prompt: 'What is the weather in Brooklyn, New York?',
+  onFinish: async () => {
+    await mcpClient.close();
+  },
+});
+```
+
+When generating responses without streaming, you can use try/finally or cleanup functions in your framework:
 
 ```typescript
 let mcpClient: MCPClient | undefined;
+
 try {
   mcpClient = await experimental_createMCPClient({
     // ...
   });
-  // ...
 } finally {
   await mcpClient?.close();
 }

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

@@ -0,0 +1,33 @@
+import { openai } from '@ai-sdk/openai';
+import { experimental_createMCPClient, streamText } from 'ai';
+
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const mcpClient = await experimental_createMCPClient({
+    transport: {
+      type: 'sse',
+      url: 'https://actions.zapier.com/mcp/[YOUR_KEY]/sse',
+    },
+  });
+
+  try {
+    const zapierTools = await mcpClient.tools();
+
+    const result = streamText({
+      model: openai('gpt-4o'),
+      messages,
+      tools: zapierTools,
+      onFinish: async () => {
+        await mcpClient.close();
+      },
+      maxSteps: 10,
+    });
+
+    return result.toDataStreamResponse();
+  } catch (error) {
+    return new Response('Internal Server Error', { status: 500 });
+  }
+}

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

@@ -0,0 +1,52 @@
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+
+export default function Page() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: '/api/mcp-zapier',
+  });
+
+  return (
+    <div className="flex flex-col items-center justify-end h-screen gap-4">
+      <h1 className="text-xl p-4">My AI Assistant</h1>
+
+      <div className="flex flex-col gap-2 p-4 mt-auto">
+        {messages.map(message => (
+          <div key={message.id}>
+            <strong>{`${message.role}: `}</strong>
+            {message.parts.map((part, index) => {
+              switch (part.type) {
+                case 'text':
+                  return <span key={index}>{part.text}</span>;
+                case 'tool-invocation': {
+                  return (
+                    <pre key={index}>
+                      {JSON.stringify(part.toolInvocation, null, 2)}
+                    </pre>
+                  );
+                }
+              }
+            })}
+          </div>
+        ))}
+      </div>
+
+      <div className="flex flex-col items-center gap-2 p-4">
+        <textarea
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Start chatting"
+          className="border-2 border-gray-300 rounded-md p-2 w-96 h-32"
+        />
+        <button
+          className="bg-blue-500 text-white p-2 rounded-md w-full px-4"
+          type="button"
+          onClick={handleSubmit}
+        >
+          Send
+        </button>
+      </div>
+    </div>
+  );
+}