feat: host-side MCP client (@tanstack/ai-mcp)

[AlemTuzlak]

Summary

Adds @tanstack/ai-mcp — a host-side Model Context Protocol client — so a server-side chat() / agent loop can discover and run tools (and read resources/prompts) from external MCP servers, across any adapter, with optional generated end-to-end types.

Built on the official @modelcontextprotocol/sdk. The runtime stays edge-deployable (Streamable HTTP is node:-free); the Node-only stdio transport is isolated behind a @tanstack/ai-mcp/stdio subpath, and the codegen CLI's heavy deps are bundled into the bin only (never the library).

How it works

An MCP client turns a server into ready-to-spread ServerTool[]; you spread them into chat({ tools }). TanStack AI never knows MCP is involved.

import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai/adapters'
import { createMCPClient } from '@tanstack/ai-mcp'

const mcp = await createMCPClient({ transport: { type: 'http', url } })
const stream = chat({ adapter: openaiText(), model: 'gpt-4o', messages, tools: await mcp.tools() })
await mcp.close()

What's included

• createMCPClient — connect to one server. Transports: Streamable HTTP (edge-safe), SSE, and stdio (via @tanstack/ai-mcp/stdio), plus a user-supplied-transport escape hatch.
• createMCPClients — multi-server pool: parallel connect, auto-prefixed tool names (collision-free by default), close-all, typed per-server access.
• Three type-safety modes:
  1. client.tools() — auto-discovery (args unknown).
  2. client.tools([toolDefinition(...)]) — bind TanStack toolDefinition()s → typed + runtime-validated, allowlisted (reuses the existing tool primitive; no parallel schema system).
  3. createMCPClient<GeneratedServer>(...) — generated end-to-end types via npx @tanstack/ai-mcp generate + mcp.config.ts (emits per-server descriptors + a combined MCPServers map; pure types, zero runtime cost).
• Resources & prompts — resources()/readResource()/resourceTemplates(), prompts()/getPrompt(), plus mcpResourceToContentPart / mcpPromptToMessages converters for seeding chat().
• Lifecycle — caller-owned close() + [Symbol.asyncDispose] (await using); chat() never closes the client (warm reuse supported).
• Core change (@tanstack/ai) — adds an optional abortSignal to ToolExecutionContext and threads the chat run's signal through tool execution, so long-running tools (e.g. MCP callTool) cancel with the run. Additive/backward-compatible.

Testing & docs

• Unit tests across the package (client, pool, tools, resources, prompts, transport, CLI) using an in-memory MCP server.
• E2E (testing/e2e): a real in-process MCP server + chat route + Playwright spec proving an MCP tool executes inside chat() and its result reaches the streamed transcript.
• New docs page docs/tools/mcp.md (+ nav/cross-links), updated tool-calling skill + a new ai-mcp skill, and a changeset (minor: @tanstack/ai-mcp, @tanstack/ai).

Notes for reviewers

• History is granular (one commit per reviewed unit) — squash-merge recommended.
• Pre-existing examples/ typecheck failures (ts-solid-chat/ts-react-chat/ts-code-mode-web, missing fetcher from docs(chat): document the fetcher chat transport for server functions #681) are unrelated to this PR and excluded from the test:pr gate.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Host-side MCP support: connect/discover/run server tools, resources, and prompts in server-side chat; multi-server pooling with auto-prefixing, typed bindings, CLI type generation, stdio transport, and abort/cancel support for long-running tool calls; new chat({ mcp }) option to manage discovery/lifecycle.
• Documentation
  • Comprehensive MCP guides, README, codegen and chat integration how-tos, examples, and migration notes.
• Tests
  • Extensive unit, type, integration, and end-to-end coverage for MCP flows.

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/ts-react-chat/src/lib/mcp-servers.ts`:
- Around line 11-29: The three transport factories (everythingTransport,
memoryTransport, sequentialThinkingTransport) call npx with unpinned package
names; change each args entry from '`@modelcontextprotocol/server-`...' to an
exact version string like '`@modelcontextprotocol/server-memory`@<exact-version>'
(and similarly for server-everything and server-sequential-thinking) so npx
installs a deterministic release. Locate the args arrays in everythingTransport,
memoryTransport, and sequentialThinkingTransport and replace the package tokens
with the exact versions used by this project (pull versions from package.json or
the lockfile) before committing.

In `@examples/ts-react-chat/src/routes/api.mcp-chat.ts`:
- Around line 51-95: The route can leak an MCP client if Promise.all rejects
partway; change the client creation so you track and clean up any
successfully-created clients on failure (e.g. use Promise.allSettled on
createMCPClient(...) for the two clients or create them sequentially), inspect
results, and if any creation failed call dispose() (or the client's teardown
method) on each fulfilled client before throwing/returning; ensure the
successful clients are only passed into chat({ mcp: { clients: [...] } }) after
you've validated both were created so MCPManager.discover()/dispose() inside
chat runs correctly.

In `@examples/ts-react-chat/src/routes/api.mcp-manual.ts`:
- Around line 23-24: Reorder the imported symbols so named exports are
alphabetized per the project's sort-imports rule: in the import from
'`@tanstack/ai-mcp`' ensure the members are sorted (createMCPClient,
mcpPromptToMessages, mcpResourceToContentPart) and in the import from
'`@tanstack/ai`' ensure (ModelMessage, StreamChunk) are sorted; update the import
lines that declare createMCPClient, mcpResourceToContentPart,
mcpPromptToMessages and the import that declares StreamChunk, ModelMessage so
their member lists are alphabetically ordered to satisfy ESLint.
- Around line 69-158: The MCP client created by createMCPClient(...) can leak if
an error happens after creation (e.g., during chat(...) or
toServerSentEventsResponse(...)); ensure client.close() is always called on
error paths by moving client declaration into the outer scope and adding a
finally or ensuring the outer catch closes the client if it exists and is not
already closed (reference createMCPClient, client.tools, client.close,
closeMcpOnDrain, chat, toServerSentEventsResponse, abortController); keep
existing early-close where client.tools() fails and still close in the outer
catch/finally so the stdio MCP process is not leaked.

In `@examples/ts-react-chat/src/routes/mcp-demo.tsx`:
- Around line 115-120: The code passes remarkGfm into the rehypePlugins array,
so GFM parsing won't run; update the component props to remove remarkGfm from
rehypePlugins and instead add it to remarkPlugins (i.e., keep rehypePlugins as
[rehypeRaw, rehypeSanitize, rehypeHighlight] and add
remarkPlugins={[remarkGfm]}), ensuring the component uses the remarkPlugins prop
with remarkGfm.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c11c09ae-c0ba-444e-bb41-dcde07e19dca

📥 Commits

Reviewing files that changed from the base of the PR and between adcc4bb and 8c5b1fb.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (7)

• examples/ts-react-chat/package.json
• examples/ts-react-chat/src/lib/mcp-servers.ts
• examples/ts-react-chat/src/routeTree.gen.ts
• examples/ts-react-chat/src/routes/api.mcp-chat.ts
• examples/ts-react-chat/src/routes/api.mcp-manual.ts
• examples/ts-react-chat/src/routes/api.mcp-pool.ts
• examples/ts-react-chat/src/routes/mcp-demo.tsx

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

examples/ts-react-chat/src/routes/api.mcp-manual.ts (1)

151-156: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Don't return raw backend error messages to the browser.

This endpoint is directly callable from the demo UI, so echoing error.message here can expose MCP/OpenAI/stdio internals to any caller. Keep the detailed diagnostics in console.error and return a fixed 500 payload instead.

Suggested fix

          return new Response(
-            JSON.stringify({ error: error.message || 'An error occurred' }),
+            JSON.stringify({ error: 'Internal server error' }),
             {
               status: 500,
               headers: { 'Content-Type': 'application/json' },
             },
           )

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/ts-react-chat/src/routes/api.mcp-manual.ts` around lines 151 - 156,
The handler currently returns JSON.stringify({ error: error.message || 'An error
occurred' }) which exposes internal backend errors to the browser; instead call
console.error(error) (or processLogger.error) to record diagnostics and replace
the response body with a fixed generic payload such as JSON.stringify({ error:
'Internal Server Error' }) while keeping status: 500 and Content-Type:
'application/json' in the new Response(...) call so no raw error.message is
echoed to clients.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@examples/ts-react-chat/src/routes/api.mcp-manual.ts`:
- Around line 151-156: The handler currently returns JSON.stringify({ error:
error.message || 'An error occurred' }) which exposes internal backend errors to
the browser; instead call console.error(error) (or processLogger.error) to
record diagnostics and replace the response body with a fixed generic payload
such as JSON.stringify({ error: 'Internal Server Error' }) while keeping status:
500 and Content-Type: 'application/json' in the new Response(...) call so no raw
error.message is echoed to clients.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: fd79d535-7a22-4b28-91a0-5e991ce866a8

📥 Commits

Reviewing files that changed from the base of the PR and between 8c5b1fb and 5be236e.

📒 Files selected for processing (4)

• examples/ts-react-chat/src/routes/api.mcp-chat.ts
• examples/ts-react-chat/src/routes/api.mcp-manual.ts
• examples/ts-react-chat/src/routes/api.mcp-pool.ts
• examples/ts-react-chat/src/routes/mcp-demo.tsx

🚧 Files skipped from review as they are similar to previous changes (3)

• examples/ts-react-chat/src/routes/api.mcp-pool.ts
• examples/ts-react-chat/src/routes/api.mcp-chat.ts
• examples/ts-react-chat/src/routes/mcp-demo.tsx

[tombeckenham]

I had to look into why you had these dynamic imports. I get it. It's the one package for the bin and the lib. If you'd imported at module level it would have added node and other dependencies into the library. It looks weird, but I'm happy with it. It's clever to be able to include the cli in the same package.

[tombeckenham]

This is great work. Really. I added a few small changes and cleaned up the docs. Ship it!