AI SDK with MCP
Use the AI SDK to call tools from a Model Context Protocol (MCP) server hosted on Vercel. The @ai-sdk/mcp client discovers the server's tools, and AI Gateway handles model requests.
Before you begin, you need:
- A JavaScript or TypeScript project with Node.js 22 or later. This example uses AI SDK 7 and ECMAScript modules (ESM).
- An AI Gateway API key.
- The
roll_diceMCP server from Deploy MCP servers to Vercel, deployed at a URL your client can reach.
Install the AI SDK and its MCP client:
pnpm i ai @ai-sdk/mcpyarn add ai @ai-sdk/mcpnpm i ai @ai-sdk/mcpbun add ai @ai-sdk/mcpSave your AI Gateway API key and deployed MCP endpoint in a .env file. Replace your-project with your deployment's domain:
AI_GATEWAY_API_KEY=your_api_key_here
MCP_SERVER_URL=https://your-project.vercel.app/api/mcpIf your MCP server requires a bearer token, also set MCP_SERVER_TOKEN to a token the server accepts. For OAuth consent and token refresh, follow Vercel Connect with AI SDK and MCP.
For a deployment with Deployment Protection, also configure automation access on the MCP client transport.
Create an entry file that connects over Streamable HTTP and passes the discovered tools to generateText. Run this code on the server or from your terminal to keep credentials private:
import { createMCPClient } from '@ai-sdk/mcp';
import { generateText, isStepCount } from 'ai';
const url = process.env.MCP_SERVER_URL;
if (!url) {
throw new Error('Set MCP_SERVER_URL in your .env file.');
}
const token = process.env.MCP_SERVER_TOKEN;
const client = await createMCPClient({
transport: {
type: 'http',
url,
...(token ? { headers: { Authorization: `Bearer ${token}` } } : {}),
},
});
try {
const tools = await client.tools();
const result = await generateText({
model: 'anthropic/claude-opus-5',
tools,
prompt: 'Use roll_dice to roll a six-sided die once.',
stopWhen: isStepCount(5),
});
console.log(result.text);
} finally {
await client.close();
}The stop condition allows up to five model steps so the model can call the tool and respond with its result. The finally block closes the MCP client after generation succeeds or fails.
Run the TypeScript example with tsx, loading credentials from .env:
pnpm dlx tsx --env-file=.env index.mtsFor JavaScript, run node --env-file=.env index.mjs. Your terminal displays the model's response with a dice result between one and six.
No. On Vercel, the AI SDK authenticates to AI Gateway with your project's OIDC token, so deployed code doesn't need AI_GATEWAY_API_KEY. A non-empty API key takes priority over OIDC, even if the key is invalid, so remove the key from your project's environment variables to use OIDC. For local development, run vercel link and vercel env pull to write VERCEL_OIDC_TOKEN to .env.local. Your MCP server token is a separate credential that you still pass in the transport's headers. See AI Gateway OIDC authentication.
Pass schemas to client.tools(). The client then loads only the tools you list and types their inputs with your Zod schemas. Add an outputSchema to validate a tool's structuredContent and get a typed result. Without schemas, client.tools() loads every tool the server offers and infers input types from the server's schemas at runtime, so your code has no compile-time type checking. See Using MCP tools in the AI SDK documentation.
Yes. The AI SDK copies each MCP tool's annotations, such as readOnlyHint and destructiveHint, to the tool call's toolMetadata.annotations. Read them in the toolApproval option and request user approval for any tool the server doesn't mark as read-only. The client doesn't create an approval policy from annotations automatically. Annotations are hints from the server, so combine them with a tool allowlist and narrowly scoped credentials. See Tool annotations and approval.
Yes, during local development. Import StdioMCPTransport from @ai-sdk/mcp/mcp-stdio and give it the command that starts the server. A stdio server runs as a subprocess of your application, so it can't serve a production deployment. In production, connect over the HTTP transport, as this guide does. The client also supports SSE for servers that still use it.
Set maxRetries on createMCPClient to retry tools/call requests after transient HTTP or network failures. Retries are off by default, so turn them on only for tools that are safe to repeat. For agents that run for a long time or wait for a person, run the agent loop with WorkflowAgent from @ai-sdk/workflow on Vercel Workflows. When you mark a tool's execute function with 'use step', each call becomes a durable step that retries up to three times by default and survives restarts. Workflow steps pass only serializable values, so create and close the MCP client inside the step that calls the tool. See What is WorkflowAgent?.
- Follow Vercel Connect with AI SDK and MCP for a streaming route with user consent and OAuth authentication.
- Configure model requests with AI SDK and AI Gateway.
- Explore MCP integrations for TanStack AI and eve examples.
Was this helpful?