Skip to content
Docs

TanStack AI with MCP

Give TanStack AI access to tools from a Model Context Protocol (MCP) server hosted on Vercel. Use @tanstack/ai-mcp to connect to the server and @tanstack/ai-vercel-gateway to send model requests through AI Gateway.

Before you begin, you need:

Install TanStack AI, its MCP client, and the AI Gateway adapter:

Terminal
pnpm i @tanstack/ai @tanstack/ai-mcp @tanstack/ai-vercel-gateway
Terminal
yarn add @tanstack/ai @tanstack/ai-mcp @tanstack/ai-vercel-gateway
Terminal
npm i @tanstack/ai @tanstack/ai-mcp @tanstack/ai-vercel-gateway
Terminal
bun add @tanstack/ai @tanstack/ai-mcp @tanstack/ai-vercel-gateway

Save your AI Gateway API key and deployed MCP endpoint in a .env file. Replace your-project with your deployment's domain:

.env
AI_GATEWAY_API_KEY=your_api_key_here
MCP_SERVER_URL=https://your-project.vercel.app/api/mcp

If you enabled OAuth authorization, also set MCP_SERVER_TOKEN to an access token your MCP server accepts. This token authenticates tool requests to your server; the AI Gateway key authenticates model requests.

For a deployment with Deployment Protection, also configure automation access on the MCP client transport.

Create an entry file that connects to the MCP server over Streamable HTTP. Run this code on the server or from your terminal to keep credentials private:

index.mts
import { chat } from '@tanstack/ai';
import { createMCPClient } from '@tanstack/ai-mcp';
import { vercelGatewayText } from '@tanstack/ai-vercel-gateway';
 
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}` } } : {}),
  },
});
 
const stream = chat({
  adapter: vercelGatewayText('anthropic/claude-opus-5'),
  messages: [
    { role: 'user', content: 'Use roll_dice to roll a six-sided die once.' },
  ],
  mcp: { clients: [client], connection: 'close' },
});
 
for await (const chunk of stream) {
  console.log(chunk);
}

When you consume the stream, chat() discovers the server's tools and makes them available to the model. TanStack AI executes requested tools through the MCP client and returns their results to the model. With connection: 'close', TanStack AI closes the client when the run finishes, errors, or aborts.

Run the TypeScript example with tsx, loading credentials from .env:

terminal
pnpm dlx tsx --env-file=.env index.mts

For JavaScript, run node --env-file=.env index.mjs. Your terminal displays stream events for the tool call, its result, and the model's response. The dice result varies between one and six.

For OAuth-protected MCP servers, use Vercel Connect to manage provider tokens and user consent. After creating and linking a connector to your project, use connectMCPTransport from @vercel/connect/tanstack-ai to configure the transport passed to createMCPClient(). The transport requests a current token from Connect before each MCP request.

Catch consent challenges with getConsentChallenge at the route boundary before streaming starts. After the user grants access, submit a new chat request. AI Gateway continues to authenticate model requests separately.

Follow the TanStack AI with Vercel Connect guide for a streaming route example, browser consent handling, and HTTP and SSE transport options.

Not with the default setting. With connection: 'close', chat() closes each client when the run succeeds, fails, or aborts. On a busy route, create the clients once at module level and pass connection: 'keep-alive' so later requests reuse the same connections. chat() never closes keep-alive clients, so your code owns them. With Fluid compute, Vercel reuses function instances across invocations, so one module-level client can serve several requests.

Yes. Pass any mix of clients and createMCPClients pools in mcp.clients. A pool adds each server's config key as a prefix to its tool names, such as github_ and linear_, so names from different servers don't collide. If two sources expose the same tool name without a prefix, the run fails with MCPDuplicateToolNameError, so set prefix on one of the clients. By default, a discovery failure on any server fails the run. To skip that server and continue, handle the error in onDiscoveryError.

Set toolFilter on the client. Pass a function such as (tool) => tool.annotations?.readOnlyHint === true, or a list of tool names. A list is strict, so discovery fails if the server has no tool with a listed name. Set needsApproval to pause for a person before matching tools run, such as every tool that isn't read-only. Annotations come from the server, so trust them only as far as you trust the server. See Limit which tools the model gets.

Pass lazyTools: true in the mcp option of chat(). TanStack AI registers every tool but sends a tool's schema only when the model asks for it, so prompts for servers with dozens of tools stay smaller. Smaller prompts use fewer input tokens on each AI Gateway request. To remove tools entirely, combine this with toolFilter. See Lazy tool discovery.

vercelGatewayText reads AI_GATEWAY_API_KEY. When that variable is absent, it uses VERCEL_OIDC_TOKEN. For local development, you can run vercel link and vercel env pull to write a development OIDC token to .env.local instead of creating an API key. To use another model, change the model ID passed to vercelGatewayText, such as anthropic/claude-opus-5. Your MCP token authenticates tool requests separately. To give the agent an isolated place to run code, see TanStack AI and Vercel Sandbox.

Last updated September 18, 2026

Was this helpful?

supported.