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:

• A JavaScript or TypeScript project with Node.js 22 or later.
• An AI Gateway API key.
• The roll_dice MCP server from Deploy MCP servers to Vercel, deployed at a URL your client can reach.

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

pnpm i @tanstack/ai @tanstack/ai-mcp @tanstack/ai-vercel-gateway

yarn add @tanstack/ai @tanstack/ai-mcp @tanstack/ai-vercel-gateway

npm i @tanstack/ai @tanstack/ai-mcp @tanstack/ai-vercel-gateway

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:

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:

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:

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.

• Use TanStack AI with AI Gateway to configure model routing and authentication.
• Follow TanStack's managed MCP guide for server routes, multiple clients, and lazy tool discovery.
• Run coding agents with TanStack AI and Vercel Sandbox.