diff --git a/.changeset/chat-mcp-option.md b/.changeset/chat-mcp-option.md
new file mode 100644
index 000000000..be74b8005
--- /dev/null
+++ b/.changeset/chat-mcp-option.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai': minor
+---
+
+Add an `mcp` option to `chat()` for managing MCP clients directly: `chat({ mcp: { clients, connection, lazyTools, onDiscoveryError } })` discovers the given MCP clients'/pools' tools at run start, merges them into the run, and (by default, `connection: 'close'`) closes them when the run ends — or keeps them warm with `connection: 'keep-alive'`. Also exports `MCPToolSource`, `ChatMCPOptions`, `MCPConnectionPolicy`, and `MCPDuplicateToolNameError` (the error thrown when tools from separate `mcp.clients` entries collide after merging; catchable with `instanceof`).
diff --git a/.changeset/mcp-server-support.md b/.changeset/mcp-server-support.md
new file mode 100644
index 000000000..6ddb1a954
--- /dev/null
+++ b/.changeset/mcp-server-support.md
@@ -0,0 +1,6 @@
+---
+'@tanstack/ai-mcp': minor
+'@tanstack/ai': minor
+---
+
+Add `@tanstack/ai-mcp`: a host-side Model Context Protocol client. Discover and run MCP server tools (and read resources/prompts) inside any adapter's `chat()` loop, with three type-safety modes (auto-discovery, hand-written `toolDefinition()` binding, and generated end-to-end types via `npx @tanstack/ai-mcp generate`). Includes `createMCPClients` for connecting to multiple servers with auto-prefixed tool names. Also exposes `abortSignal` on `ToolExecutionContext` so long-running tools (e.g. MCP `callTool`) cancel with the chat run.
diff --git a/.changeset/strip-unsupported-openai-formats.md b/.changeset/strip-unsupported-openai-formats.md
new file mode 100644
index 000000000..61d9f39df
--- /dev/null
+++ b/.changeset/strip-unsupported-openai-formats.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/openai-base': patch
+---
+
+Strip JSON Schema `format` values that OpenAI's strict Structured Outputs subset rejects (e.g. `uri`, `uri-reference`, `iri`) from tool and response schemas before sending. Tools whose input schemas declare an unsupported `format` — common with MCP server tools — previously caused the entire request to fail with `400 ... '<format>' is not a valid format`. Supported formats (`date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, `uuid`) are preserved, and the caller's original tool definition is never mutated.
diff --git a/docs/config.json b/docs/config.json
index f45ce573c..9efb1a5af 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -86,6 +86,22 @@
         {
           "label": "Lazy Tool Discovery",
           "to": "tools/lazy-tool-discovery"
+        },
+        {
+          "label": "MCP Server Tools",
+          "to": "tools/mcp"
+        },
+        {
+          "label": "Managed MCP with chat()",
+          "to": "tools/mcp-managed"
+        },
+        {
+          "label": "Manual MCP: Tools, Resources & Prompts",
+          "to": "tools/mcp-manual"
+        },
+        {
+          "label": "MCP Type Generation",
+          "to": "tools/mcp-codegen"
         }
       ]
     },
diff --git a/docs/tools/mcp-codegen.md b/docs/tools/mcp-codegen.md
new file mode 100644
index 000000000..ee7039020
--- /dev/null
+++ b/docs/tools/mcp-codegen.md
@@ -0,0 +1,122 @@
+---
+title: MCP Type Generation
+id: mcp-codegen
+order: 11
+description: "Generate per-server TypeScript interface types from a live MCP server and wire them into createMCPClient for typed tool names and compile-checked pool keys."
+keywords:
+  - tanstack ai
+  - mcp
+  - model context protocol
+  - codegen
+  - type safety
+  - mcp.config.ts
+  - defineConfig
+  - createMCPClient
+  - generated types
+---
+
+You have a running MCP server and you call its tools through [`createMCPClient`](./mcp), but nothing checks the tool names you reference at compile time. By the end of this guide you'll have generated per-server `interface` types from the live server and wired them into `createMCPClient`, narrowing discovered tool names to the server's literal names and compile-checking pool config keys — with zero runtime overhead. This is [Mode 3](./mcp#mode-3--generated-types-createmcpclientgeneratedserver) of MCP type safety. (Tool *arguments* stay untyped on the discovery path — for Zod-validated, TypeScript-typed arguments, combine with the [`tools([toolDefinition(...)])` overload](./mcp#mode-2--explicit-definitions-clienttoolsdefs).)
+
+The `generate` CLI introspects a live MCP server and emits TypeScript interface types that you pass as a generic to `createMCPClient` / `createMCPClients`.
+
+## 1. Create `mcp.config.ts`
+
+Declare each server you want to generate types for. The `defineConfig` helper gives the config file full type checking and autocomplete.
+
+```ts
+// mcp.config.ts
+import { defineConfig } from '@tanstack/ai-mcp'
+
+export default defineConfig({
+  servers: {
+    github: {
+      transport: { type: 'http', url: 'https://github-mcp.example.com/mcp' },
+    },
+    linear: {
+      transport: { type: 'http', url: 'https://linear-mcp.example.com/mcp' },
+      prefix: 'linear', // must match runtime createMCPClient({ prefix })
+    },
+  },
+  outFile: './mcp-types.generated.ts',
+})
+```
+
+## 2. Run the generator
+
+```bash
+npx @tanstack/ai-mcp generate
+```
+
+The CLI connects to each declared server, introspects its tools, resources, and prompts, and writes the result to `outFile`.
+
+## 3. Inspect the output
+
+The generator emits one interface per server plus a combined pool map:
+
+```ts
+// AUTO-GENERATED by `npx @tanstack/ai-mcp generate`. Do not edit.
+
+import type { ServerDescriptor } from '@tanstack/ai-mcp'
+
+export interface GithubServer extends ServerDescriptor {
+  tools: {
+    'search_repositories': { input: { query: string; limit?: number }; output: unknown }
+    'create_issue': { input: { repo: string; title: string; body?: string }; output: unknown }
+  }
+  resources: {}
+  prompts: {}
+  capabilities: { tools: {} } & Record<string, unknown>
+}
+
+export interface LinearServer extends ServerDescriptor {
+  tools: {
+    'linear_create_issue': { input: { title: string; teamId: string }; output: unknown }
+  }
+  resources: {}
+  prompts: {}
+  capabilities: { tools: {} } & Record<string, unknown>
+}
+
+export interface MCPServers extends Record<string, ServerDescriptor> {
+  'github': GithubServer
+  'linear': LinearServer
+}
+```
+
+## 4. Use generated types at runtime
+
+Pass the generated type as a generic to [`createMCPClient`](./mcp) (single server) or `createMCPClients` (pool). Tool names are narrowed to the literal types declared by the server, so a typo is a compile error.
+
+**Single server:**
+
+```ts
+import type { GithubServer } from './mcp-types.generated'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+const mcp = await createMCPClient<GithubServer>({
+  transport: { type: 'http', url: process.env.GITHUB_MCP_URL! },
+})
+
+const tools = await mcp.tools()
+// Each tool name is narrowed from GithubServer['tools']
+```
+
+**Multi-server pool:**
+
+```ts
+import type { MCPServers } from './mcp-types.generated'
+import { createMCPClients } from '@tanstack/ai-mcp'
+
+const pool = await createMCPClients<MCPServers>({
+  github: { transport: { type: 'http', url: process.env.GITHUB_MCP_URL! } },
+  linear: {
+    transport: { type: 'http', url: process.env.LINEAR_MCP_URL! },
+    prefix: 'linear',
+  },
+})
+
+// Config keys are constrained to the declared servers — a typo is a compile error
+const tools = await pool.tools()
+```
+
+Now that tool names and pool keys are compile-checked, hand the generated client to `chat()`. See [Managed MCP with `chat()`](./mcp-managed) to let `chat()` own discovery and lifecycle.
diff --git a/docs/tools/mcp-managed.md b/docs/tools/mcp-managed.md
new file mode 100644
index 000000000..3db4f8022
--- /dev/null
+++ b/docs/tools/mcp-managed.md
@@ -0,0 +1,306 @@
+---
+title: Managed MCP with chat()
+id: mcp-managed
+order: 9
+description: "Hand live MCP clients and pools to chat() via the mcp option and let it own tool discovery and connection lifecycle for you."
+keywords:
+  - tanstack ai
+  - mcp
+  - model context protocol
+  - chat mcp
+  - mcp clients
+  - keep-alive
+  - lazyTools
+  - onDiscoveryError
+---
+
+You have one or more live [MCP clients](./mcp) (or pools) and you want the model to use their tools — without writing boilerplate `await client.tools()` calls and `try/finally close()` blocks for every route. By the end of this guide you'll hand those clients to `chat()` via the `mcp` option and let it handle both discovery and lifecycle for you.
+
+> **Managed (`mcp` prop) vs manual (`tools` spread)**
+>
+> - Use `mcp: { clients: [...] }` when you want **discovery + lifecycle** managed for you and you are happy with runtime-typed (`unknown`-argument) tools.
+> - Use `tools: [...await client.tools([toolDefinition(...)])]` when you need **fully-typed MCP tools** — the defs overload gives you Zod-validated, TypeScript-typed arguments. See [Manual MCP: typed tools, resources & prompts](./mcp-manual) and [Three Modes of Type Safety](./mcp#three-modes-of-type-safety).
+>
+> Both coexist in the same `chat()` call. Tools from `mcp.clients` are merged with any tools you pass explicitly via `tools`.
+
+## Hand a client to `chat()`
+
+The simplest path: create a client, hand it to `chat()`, and let the run clean it up. `connection` defaults to `'close'`, so the client is closed automatically once the run ends — on success, error, or abort.
+
+```ts
+// src/routes/api.chat.ts
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai/adapters'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        const mcpClient = await createMCPClient({
+          transport: {
+            type: 'http',
+            url: process.env.MCP_URL!,
+            headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` },
+          },
+        })
+
+        // chat() discovers mcpClient's tools and closes the connection when done.
+        // No try/finally needed.
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          mcp: {
+            clients: [mcpClient],
+            // connection: 'close' is the default — shown here for clarity
+            connection: 'close',
+          },
+        })
+
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+The examples below show only the part that changes — the client setup and the `chat()` call. They all drop into the same route handler shape as above.
+
+## Multiple servers and pools
+
+Pass any mix of `MCPClient` instances and `MCPClients` pools. Their tools are discovered in parallel and merged into one flat tool set. Pools auto-prefix each server's tools with the config key to prevent name collisions.
+
+```ts
+import { createMCPClient, createMCPClients } from '@tanstack/ai-mcp'
+
+// A pool of two servers — their tools are prefixed "github_" and "linear_"
+const githubLinearPool = await createMCPClients({
+  github: {
+    transport: {
+      type: 'http',
+      url: process.env.GITHUB_MCP_URL!,
+      headers: { Authorization: `Bearer ${process.env.GITHUB_MCP_TOKEN}` },
+    },
+  },
+  linear: {
+    transport: {
+      type: 'http',
+      url: process.env.LINEAR_MCP_URL!,
+      headers: { Authorization: `Bearer ${process.env.LINEAR_MCP_TOKEN}` },
+    },
+  },
+})
+
+// A standalone client for an internal server
+const internalClient = await createMCPClient({
+  transport: { type: 'http', url: process.env.INTERNAL_MCP_URL! },
+})
+
+// All three servers' tools are merged: github_*, linear_*, plus internal tools
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  mcp: {
+    clients: [githubLinearPool, internalClient],
+    connection: 'close',
+  },
+})
+```
+
+## Keep connections warm
+
+Creating a new MCP connection on every request adds latency. For production routes with high request rates, create your pool once at module level and pass `connection: 'keep-alive'` so `chat()` never closes it. The pool stays ready for the next request. (Shown as a full route because the placement — module scope vs. handler scope — is the point.)
+
+**Server route (`src/routes/api.chat.ts`):**
+
+```ts
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai/adapters'
+import { createMCPClients } from '@tanstack/ai-mcp'
+
+// Created once when the module loads. Shared across all requests.
+const sharedPool = await createMCPClients({
+  github: {
+    transport: {
+      type: 'http',
+      url: process.env.GITHUB_MCP_URL!,
+      headers: { Authorization: `Bearer ${process.env.GITHUB_MCP_TOKEN}` },
+    },
+  },
+  linear: {
+    transport: {
+      type: 'http',
+      url: process.env.LINEAR_MCP_URL!,
+      headers: { Authorization: `Bearer ${process.env.LINEAR_MCP_TOKEN}` },
+    },
+  },
+})
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        // keep-alive: sharedPool is never closed by chat(); stays warm for next call
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          mcp: {
+            clients: [sharedPool],
+            connection: 'keep-alive',
+          },
+        })
+
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+**Client component (`src/components/Chat.tsx`):**
+
+```tsx
+import { useChat } from '@tanstack/ai-react'
+import { fetchServerSentEvents } from '@tanstack/ai-client'
+
+const chatOptions = {
+  connection: fetchServerSentEvents('/api/chat'),
+}
+
+export function Chat() {
+  const { messages, sendMessage, status } = useChat(chatOptions)
+
+  return (
+    <div>
+      <ul>
+        {messages.map((m) => (
+          <li key={m.id}>
+            <strong>{m.role}:</strong> {m.content}
+          </li>
+        ))}
+      </ul>
+      <button
+        onClick={() => sendMessage({ content: 'List my open GitHub issues' })}
+        disabled={status === 'streaming'}
+      >
+        Ask
+      </button>
+    </div>
+  )
+}
+```
+
+## Lazy tool discovery
+
+When your MCP server exposes dozens of tools, sending every schema to the model inflates prompt size and cost. Set `lazyTools: true` to defer sending tool schemas until the model explicitly requests them.
+
+```ts
+const mcpClient = await createMCPClient({
+  transport: { type: 'http', url: process.env.LARGE_MCP_URL! },
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  mcp: {
+    clients: [mcpClient],
+    connection: 'close',
+    // Tools are registered but schemas are withheld until the model asks
+    lazyTools: true,
+  },
+})
+```
+
+`lazyTools: true` is forwarded to each source's `tools({ lazy: true })` call. See [Lazy Tool Discovery](./lazy-tool-discovery) for how the model discovers and loads lazy tools at runtime, and [the standalone lazy discovery section](./mcp#lazy-tool-discovery) for using `{ lazy: true }` directly with `client.tools()`.
+
+## Handling discovery failures
+
+By default, if any source fails during discovery, `chat()` throws immediately (fail-fast). When `connection: 'close'`, any sources that did connect are cleaned up before the error propagates — no leaked connections.
+
+**Fail-fast (default):**
+
+```ts
+const mcpClient = await createMCPClient({
+  transport: { type: 'http', url: process.env.MCP_URL! },
+})
+
+// If discovery fails, chat() throws before the first model call.
+// mcpClient is closed automatically (connection: 'close' default).
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  mcp: {
+    clients: [mcpClient],
+  },
+})
+```
+
+**Skip a flaky server and proceed:**
+
+Use `onDiscoveryError` to log the problem and return normally — the failing source is skipped and the run continues with the remaining clients' tools.
+
+```ts
+const primaryClient = await createMCPClient({
+  transport: { type: 'http', url: process.env.PRIMARY_MCP_URL! },
+})
+
+const optionalClient = await createMCPClient({
+  transport: { type: 'http', url: process.env.OPTIONAL_MCP_URL! },
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  mcp: {
+    clients: [primaryClient, optionalClient],
+    connection: 'close',
+    onDiscoveryError(error, source) {
+      // Log the failure but let the run proceed without this source's tools.
+      // Throw here (or re-throw `error`) to fail the whole run instead.
+      console.warn('MCP discovery failed for a source, skipping.', error)
+    },
+  },
+})
+```
+
+> Sources passed to `onDiscoveryError` may have already connected before discovery failed. When `connection: 'close'`, they are still closed at the end of the run — even if their tools were skipped.
+
+## Tool name collisions
+
+If two sources in `mcp.clients` expose a tool with the same name, the run fails with an `MCPDuplicateToolNameError` (exported from `@tanstack/ai`) after merging the discovered tools. Note that `chat()` runs lazily — discovery happens when the stream is first consumed, so the error surfaces **through the stream** (the SSE response errors), not as a synchronous throw you can `try/catch` at the `chat()` call site. The fix is to prevent the collision up front: assign a `prefix` to one of the clients, or use `createMCPClients` (which auto-prefixes using the config key).
+
+```ts
+// Both servers expose a tool called "search". Without prefixes the run
+// would fail with MCPDuplicateToolNameError. The prefix option resolves
+// the clash.
+const serverA = await createMCPClient({
+  transport: { type: 'http', url: process.env.SERVER_A_URL! },
+  prefix: 'alpha', // tools become "alpha_search", etc.
+})
+
+const serverB = await createMCPClient({
+  transport: { type: 'http', url: process.env.SERVER_B_URL! },
+  prefix: 'beta', // tools become "beta_search", etc.
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  mcp: {
+    clients: [serverA, serverB],
+    connection: 'close',
+  },
+})
+```
+
+For the standalone `pool.tools()` collision behavior and the general `prefix` strategy, see [Tool Name Collisions](./mcp#tool-name-collisions) and [Disable or override the prefix](./mcp#disable-or-override-the-prefix).
+
+## Going further
+
+> **Need fully-typed tools, resources, or prompts in the run?** The `mcp` prop gives you runtime-typed tools and discovery. To spread `toolDefinition`-typed MCP tools, inject MCP resources and prompts, or cancel in-flight MCP calls, see [Manual MCP: typed tools, resources & prompts](./mcp-manual).
diff --git a/docs/tools/mcp-manual.md b/docs/tools/mcp-manual.md
new file mode 100644
index 000000000..87f5e55af
--- /dev/null
+++ b/docs/tools/mcp-manual.md
@@ -0,0 +1,291 @@
+---
+title: "Manual MCP: typed tools, resources & prompts"
+id: mcp-manual
+order: 10
+description: "Spread fully-typed MCP tools into chat(), inject MCP resources and prompts as content and messages, and cancel in-flight MCP tool calls."
+keywords:
+  - tanstack ai
+  - mcp
+  - model context protocol
+  - mcp resources
+  - mcp prompts
+  - mcpResourceToContentPart
+  - mcpPromptToMessages
+  - cancellation
+  - abortController
+---
+
+You have a live [MCP client](./mcp) and want to do more than auto-discover tools: spread fully-typed tools into a `chat()` run, inject the server's resources and prompts into the conversation, and cancel in-flight MCP calls when the run aborts. By the end of this guide you'll have wired all of these into a single `chat()` call.
+
+> **Manual (`tools` spread) vs managed (`mcp` prop)**
+>
+> This page covers the **manual** path — you call `client.tools()` / `client.resources()` / `client.getPrompt()` yourself and own `close()`. If you only need runtime-typed tools with discovery and lifecycle handled for you, use the `mcp` prop instead — see [Managed MCP with `chat()`](./mcp-managed). Both paths build on the [`createMCPClient` basics](./mcp).
+
+## Fully-typed tools via the `tools` spread
+
+Pass `toolDefinition()` instances to `client.tools([...])` to get Zod-validated, TypeScript-typed arguments ([Mode 2](./mcp#mode-2--explicit-definitions-clienttoolsdefs)), then spread the result into `chat()`'s `tools` option. You own the client, so you must close it — but **not before the stream is consumed**: `chat()` executes tools lazily while the response streams, so closing in a `finally` around the `return` would kill in-flight tool calls. Close in a middleware terminal hook instead (exactly one of `onFinish`/`onAbort`/`onError` fires per run).
+
+```ts
+// src/routes/api.chat.ts
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse, toolDefinition } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai/adapters'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { z } from 'zod'
+
+const searchDef = toolDefinition({
+  name: 'search',
+  description: 'Search for items',
+  inputSchema: z.object({ query: z.string() }),
+  outputSchema: z.array(z.object({ id: z.string(), title: z.string() })),
+})
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        const mcp = await createMCPClient({
+          transport: { type: 'http', url: process.env.MCP_URL! },
+        })
+
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          // Fully-typed MCP tools, merged with any other tools you pass
+          tools: [...(await mcp.tools([searchDef]))],
+          // Close after the run ends — tools execute while the response streams.
+          middleware: [
+            {
+              name: 'mcp-close',
+              onFinish: () => mcp.close(),
+              onAbort: () => mcp.close(),
+              onError: () => mcp.close(),
+            },
+          ],
+        })
+
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+## Resources
+
+MCP resources are context documents (files, database records, web pages) the server exposes. Fetch them and inject them into `chat()` as content parts.
+
+```ts
+import { mcpResourceToContentPart } from '@tanstack/ai-mcp'
+
+const resources = await mcp.resources()
+// resources: Array<{ uri: string; name: string; ... }>
+
+const readResult = await mcp.readResource(resources[0].uri)
+const parts = readResult.contents.map(mcpResourceToContentPart)
+
+// Inject as part of a user message
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages: [
+    {
+      role: 'user',
+      content: [
+        ...parts,
+        { type: 'text', content: 'Summarize the above document.' },
+      ],
+    },
+  ],
+})
+```
+
+`mcpResourceToContentPart` maps each MCP content block to a `ContentPart`:
+- `text` field present → `{ type: 'text', content: text }`
+- `blob` field present → `{ type: 'text', content: '[binary resource <uri>]' }`
+- otherwise → `{ type: 'text', content: JSON.stringify(content) }`
+
+### Resource templates
+
+```ts
+const templates = await mcp.resourceTemplates()
+// templates: Array<ResourceTemplate>
+```
+
+## Prompts
+
+MCP prompts are reusable message templates the server exposes. Fetch a prompt, convert it to `ModelMessage[]` with `mcpPromptToMessages`, and spread it into `chat()` to seed the conversation with server-defined context or instructions.
+
+```ts
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai/adapters'
+import { createMCPClient, mcpPromptToMessages } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        const mcp = await createMCPClient({
+          transport: { type: 'http', url: process.env.MCP_URL! },
+        })
+
+        try {
+          // List all available prompts on the server
+          const available = await mcp.prompts()
+          // available: Array<{ name: string; description?: string; arguments?: ... }>
+
+          // Fetch a specific prompt, optionally passing template arguments
+          const prompt = await mcp.getPrompt('summarize', { language: 'english' })
+
+          const stream = chat({
+            adapter: openaiText('gpt-5.5'),
+            messages: [
+              // Seed the conversation with the server-defined prompt messages
+              ...mcpPromptToMessages(prompt),
+              // Then append the user's own messages
+              ...messages,
+            ],
+          })
+
+          return toServerSentEventsResponse(stream)
+        } finally {
+          // Safe here: all MCP calls (prompts/getPrompt) completed before chat()
+          // started, and no MCP tools are passed to the run. If you also spread
+          // MCP tools into `tools`, close in a middleware terminal hook instead
+          // (see "Fully-typed tools via the `tools` spread" above).
+          await mcp.close()
+        }
+      },
+    },
+  },
+})
+```
+
+`mcpPromptToMessages` maps each MCP prompt message to a `ModelMessage`:
+- `role === 'assistant'` → `{ role: 'assistant', content: text }`
+- any other role → `{ role: 'user', content: text }`
+- non-text content → `content` is `JSON.stringify`'d
+
+`getPrompt(name, args?)` accepts an optional `args` parameter typed as `Record<string, string>` for filling in template variables declared by the prompt.
+
+## Cancellation
+
+When the chat run is cancelled (e.g. the user navigates away or an `AbortController` fires), in-flight MCP `callTool` requests are cancelled automatically. The abort signal from the chat run is threaded through `ToolExecutionContext.abortSignal` into each tool's execute function.
+
+```ts
+const controller = new AbortController()
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  tools: await mcp.tools(),
+  abortController: controller,
+})
+
+// Cancel the run and all in-flight MCP tool calls:
+controller.abort()
+```
+
+## Full Server + Client Example
+
+Here is a complete TanStack Start API route that connects to two MCP servers and streams the response to the browser.
+
+**Server route (`src/routes/api.chat.ts`):**
+
+```ts
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai/adapters'
+import { createMCPClients } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const body = await request.json()
+
+        if (typeof body !== 'object' || body === null || !Array.isArray(body.messages)) {
+          return new Response('Bad request', { status: 400 })
+        }
+
+        const pool = await createMCPClients({
+          github: {
+            transport: {
+              type: 'http',
+              url: process.env.GITHUB_MCP_URL!,
+              headers: { Authorization: `Bearer ${process.env.GITHUB_MCP_TOKEN}` },
+            },
+          },
+          linear: {
+            transport: {
+              type: 'http',
+              url: process.env.LINEAR_MCP_URL!,
+              headers: { Authorization: `Bearer ${process.env.LINEAR_MCP_TOKEN}` },
+            },
+          },
+        })
+
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages: body.messages,
+          tools: await pool.tools(),
+          // Close after the run ends — tools execute while the response streams.
+          middleware: [
+            {
+              name: 'mcp-close',
+              onFinish: () => pool.close(),
+              onAbort: () => pool.close(),
+              onError: () => pool.close(),
+            },
+          ],
+        })
+
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+**Client component (`src/components/Chat.tsx`):**
+
+```tsx
+import { useChat } from '@tanstack/ai-react'
+import { fetchServerSentEvents } from '@tanstack/ai-client'
+
+const chatOptions = {
+  connection: fetchServerSentEvents('/api/chat'),
+}
+
+export function Chat() {
+  const { messages, sendMessage, status } = useChat(chatOptions)
+
+  return (
+    <div>
+      <ul>
+        {messages.map((m) => (
+          <li key={m.id}>
+            <strong>{m.role}:</strong> {m.content}
+          </li>
+        ))}
+      </ul>
+      <button
+        onClick={() => sendMessage({ content: 'List my open GitHub issues' })}
+        disabled={status === 'streaming'}
+      >
+        Ask
+      </button>
+    </div>
+  )
+}
+```
+
+## Going further
+
+> **Want `chat()` to discover tools and close clients for you?** If you don't need the manual `tools` spread, resources, or prompts, the `mcp` prop removes the close-middleware boilerplate entirely. See [Managed MCP with `chat()`](./mcp-managed).
+
+> **Want compile-checked tool names on the discovery path?** Generate per-server interface types from your live servers and pass them as a generic to `createMCPClient` — discovered tool names narrow to the server's literal names, with zero runtime overhead. See [MCP Type Generation](./mcp-codegen).
diff --git a/docs/tools/mcp.md b/docs/tools/mcp.md
new file mode 100644
index 000000000..d44e879c9
--- /dev/null
+++ b/docs/tools/mcp.md
@@ -0,0 +1,427 @@
+---
+title: MCP Server Tools
+id: mcp
+order: 8
+description: "Connect TanStack AI to any Model Context Protocol server with createMCPClient to discover and execute its tools."
+keywords:
+  - tanstack ai
+  - mcp
+  - model context protocol
+  - mcp tools
+  - mcp client
+  - server tools
+  - createMCPClient
+  - createMCPClients
+  - type safety
+---
+
+`@tanstack/ai-mcp` is a host-side [Model Context Protocol](https://modelcontextprotocol.io) client for TanStack AI. It connects your server route to any MCP-compliant server and makes that server's tools, resources, and prompts available inside `chat()`.
+
+> MCP tool execution is **server-side only**. The `createMCPClient` call lives in a server route (or serverless function) — never in browser code.
+
+## Installation
+
+```bash
+pnpm add @tanstack/ai-mcp @modelcontextprotocol/sdk
+```
+
+## Quick Start
+
+The simplest integration is the managed `mcp` option: hand the client to `chat()` and it discovers the tools and closes the connection when the run ends — no lifecycle code at all.
+
+```ts
+// src/routes/api.chat.ts  (TanStack Start)
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai/adapters'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        const mcp = await createMCPClient({
+          transport: {
+            type: 'http',
+            url: 'https://my-mcp-server.example.com/mcp',
+          },
+        })
+
+        // chat() discovers the tools and closes the client when the run ends.
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          mcp: { clients: [mcp] },
+        })
+
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+> Need fully-typed tool arguments, resources, prompts, or your own lifecycle? Spread tools manually instead — see [Manual MCP: typed tools, resources & prompts](./mcp-manual) and the [Lifecycle](#lifecycle) section below.
+
+On the client side, consume the stream with `useChat` exactly as you would any other TanStack AI endpoint:
+
+```tsx
+// src/components/Chat.tsx
+import { useChat } from '@tanstack/ai-react'
+import { fetchServerSentEvents } from '@tanstack/ai-client'
+
+export function Chat() {
+  const { messages, sendMessage, status } = useChat({
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+      <button
+        onClick={() => sendMessage({ content: 'Hello' })}
+        disabled={status === 'streaming'}
+      >
+        Send
+      </button>
+    </div>
+  )
+}
+```
+
+## Transports
+
+### HTTP (Streamable HTTP)
+
+The preferred transport for remote servers. Uses the MCP Streamable HTTP protocol.
+
+```ts
+const mcp = await createMCPClient({
+  transport: {
+    type: 'http',
+    url: 'https://my-mcp-server.example.com/mcp',
+    headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` },
+  },
+})
+```
+
+### SSE (Server-Sent Events)
+
+For servers that implement the legacy SSE transport.
+
+```ts
+const mcp = await createMCPClient({
+  transport: {
+    type: 'sse',
+    url: 'https://my-mcp-server.example.com/sse',
+    headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` },
+  },
+})
+```
+
+### stdio (Node.js only)
+
+For spawning a local MCP process. Because stdio imports Node-native modules, it is isolated behind a subpath import so edge bundles stay clean.
+
+```ts
+import { stdioTransport } from '@tanstack/ai-mcp/stdio'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+const mcp = await createMCPClient({
+  transport: stdioTransport({
+    command: 'node',
+    args: ['./my-mcp-server.js'],
+    env: { API_KEY: process.env.API_KEY ?? '' },
+  }),
+})
+```
+
+### Custom transport (escape hatch)
+
+Pass any `Transport` instance directly as the `transport` option. For in-process testing, `InMemoryTransport` is re-exported from `@tanstack/ai-mcp`:
+
+```ts
+import { createMCPClient, InMemoryTransport } from '@tanstack/ai-mcp'
+
+const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
+const mcp = await createMCPClient({ transport: clientTransport })
+```
+
+For a custom network transport, pass any SDK `Transport`-compatible instance:
+
+```ts
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+
+const transport = new StreamableHTTPClientTransport(new URL('https://example.com/mcp'))
+const mcp = await createMCPClient({ transport })
+```
+
+## Authentication
+
+### Static tokens (headers)
+
+For servers that take a pre-provisioned API key or bearer token, pass `headers` on the `http`/`sse` transport config — they are sent with every request:
+
+```ts
+const mcp = await createMCPClient({
+  transport: {
+    type: 'http',
+    url: 'https://my-mcp-server.example.com/mcp',
+    headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` },
+  },
+})
+```
+
+### OAuth (`authProvider`)
+
+For servers implementing the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) (OAuth 2.1), pass an `authProvider` on the `http`/`sse` transport config. It accepts any `OAuthClientProvider` from the official SDK (`@modelcontextprotocol/sdk/client/auth.js`); the SDK transport then handles attaching tokens, refreshing them, and retrying on 401 — no extra wiring in TanStack AI.
+
+```ts
+import { createMCPClient } from '@tanstack/ai-mcp'
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js'
+
+// Server-side: back the provider with tokens you persist (database, KV, ...).
+// `tokens()` returning a valid (or refreshable) token set is all the SDK
+// needs to authenticate requests.
+declare const myOAuthProvider: OAuthClientProvider
+
+const mcp = await createMCPClient({
+  transport: {
+    type: 'http',
+    url: 'https://my-mcp-server.example.com/mcp',
+    authProvider: myOAuthProvider,
+  },
+})
+```
+
+> **Interactive authorization (redirect flows).** Completing an authorization-code
+> grant requires calling `finishAuth(code)` on the transport after the user is
+> redirected back — and `createMCPClient` constructs the transport internally,
+> so it cannot expose it. If you need the interactive flow, build the transport
+> yourself and pass it in (the escape hatch above): construct a
+> `StreamableHTTPClientTransport` with your `authProvider`, keep a reference,
+> call `transport.finishAuth(code)` in your OAuth callback route, then hand the
+> transport to `createMCPClient({ transport })`. For typical server-side use —
+> a provider backed by pre-provisioned or stored tokens with working refresh —
+> the config form shown above is all you need.
+
+## Three Modes of Type Safety
+
+### Mode 1 — Auto-discovery (`client.tools()`)
+
+Call `tools()` with no arguments to discover every tool the server exposes. This requires no extra setup. Tool argument types are `unknown` at compile time; the MCP JSON Schema is used for runtime validation.
+
+```ts
+const tools = await mcp.tools()
+// tools: ServerTool[]  — args typed unknown at compile time
+```
+
+> **Task-based tools are excluded.** Tools that declare
+> `execution.taskSupport: 'required'` (the experimental MCP tasks feature)
+> can only run through the SDK's `tasks/callToolStream` flow, which
+> `@tanstack/ai-mcp` does not support yet — plain `callTool` is rejected by
+> the server with `-32600`. Discovery skips them so the model is never
+> offered a tool that cannot succeed.
+
+### Mode 2 — Explicit definitions (`client.tools([...defs])`)
+
+Pass TanStack `toolDefinition()` instances to get full TypeScript types and Zod validation. Only the named tools are returned (allowlist). `MCPToolNotFoundError` is thrown if a name isn't on the server, and `MCPTaskRequiredToolError` if the named tool requires task-based execution (see the Mode 1 note).
+
+```ts
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+const searchDef = toolDefinition({
+  name: 'search',
+  description: 'Search for items',
+  inputSchema: z.object({ query: z.string() }),
+  outputSchema: z.array(z.object({ id: z.string(), title: z.string() })),
+})
+
+const tools = await mcp.tools([searchDef])
+// tools[0].execute is typed: (args: { query: string }) => ...
+```
+
+### Mode 3 — Generated types (`createMCPClient<GeneratedServer>`)
+
+Run the CLI against a live server to generate per-server `interface` types, then pass the generated type as a generic — tool names are narrowed to the server's literal names and pool config keys are compile-checked, with zero runtime overhead. (Tool *arguments* stay untyped on the discovery path — combine with Mode 2 for typed args.)
+
+> See [MCP Type Generation](./mcp-codegen) for the full `mcp.config.ts` setup, the `generate` CLI, and how to wire the generated types into `createMCPClient` and `createMCPClients`.
+
+## Multi-Server Pool
+
+`createMCPClients` connects to many servers in parallel and merges their tools into one flat array. Each server's tools are automatically prefixed with the config key to prevent name collisions.
+
+```ts
+import { createMCPClients } from '@tanstack/ai-mcp'
+
+const pool = await createMCPClients({
+  github: { transport: { type: 'http', url: process.env.GITHUB_MCP_URL! } },
+  linear: { transport: { type: 'http', url: process.env.LINEAR_MCP_URL! } },
+})
+
+// tools: [github_search_repos, github_create_issue, linear_create_issue, ...]
+const tools = await pool.tools()
+```
+
+`pool.tools()` collects all servers' tools and throws `DuplicateToolNameError` if any two names collide after prefixing.
+
+### Per-server access
+
+```ts
+const linearTools = await pool.clients.linear.tools()
+const resources = await pool.clients.github.resources()
+```
+
+### Disable or override the prefix
+
+```ts
+const pool = await createMCPClients({
+  github: {
+    transport: { type: 'http', url: process.env.GITHUB_MCP_URL! },
+    prefix: 'gh',           // override: "gh_search_repos"
+  },
+  internal: {
+    transport: { type: 'http', url: process.env.INTERNAL_MCP_URL! },
+    prefix: '',             // disable prefix entirely
+  },
+})
+```
+
+### Closing the pool
+
+```ts
+await pool.close()
+// or
+await using pool = await createMCPClients({ ... })
+```
+
+If any server fails to connect, already-connected clients are closed before the error is thrown — no leaks.
+
+## Lifecycle
+
+> **You can skip this entire section** by passing clients to `chat()` via the `mcp` option (as in the Quick Start) — `chat()` discovers tools and closes the connections when the run ends. See [Managed MCP with `chat()`](./mcp-managed). Read on only if you spread tools manually and own `close()` yourself.
+
+When you manage the client manually, it is **caller-owned**: `chat()` never closes it.
+
+Tools execute **lazily while the response stream is consumed**, so only close the client after the stream is fully drained. In a route handler that returns a streaming `Response`, a `try/finally` around the `return` (or `await using` at function scope) closes the client *before* the body streams — in-flight tool calls would fail. Close in a middleware terminal hook instead.
+
+### Streaming route handlers — close via middleware
+
+Exactly one of `onFinish`/`onAbort`/`onError` fires per run, after the agent loop ends:
+
+```ts
+const mcp = await createMCPClient({ transport: { type: 'http', url } })
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  tools: await mcp.tools(),
+  middleware: [
+    {
+      name: 'mcp-close',
+      onFinish: () => mcp.close(),
+      onAbort: () => mcp.close(),
+      onError: () => mcp.close(),
+    },
+  ],
+})
+return toServerSentEventsResponse(stream)
+```
+
+### Manual close — when you consume the stream in scope
+
+`try/finally` is correct when the stream is drained before the scope exits:
+
+```ts
+const mcp = await createMCPClient({ transport: { type: 'http', url } })
+try {
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages,
+    tools: await mcp.tools(),
+  })
+  for await (const chunk of stream) {
+    // handle chunks — the stream is fully consumed inside this block
+  }
+} finally {
+  await mcp.close()
+}
+```
+
+### `await using` (Explicit Resource Management)
+
+If your runtime supports `Symbol.asyncDispose` (Node 18.2+ with TypeScript `target: "es2022"` + `lib: ["esnext"]`), the same in-scope-consumption rule applies — the client closes when the block exits:
+
+```ts
+await using mcp = await createMCPClient({ transport: { type: 'http', url } })
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  tools: await mcp.tools(),
+})
+for await (const chunk of stream) {
+  // handle chunks
+}
+// mcp.close() is called automatically when the block exits
+```
+
+## Tool Name Collisions
+
+When mixing tools from multiple sources, duplicate names throw `DuplicateToolNameError`:
+
+```ts
+import { DuplicateToolNameError } from '@tanstack/ai-mcp'
+
+try {
+  const tools = await pool.tools()
+} catch (err) {
+  if (err instanceof DuplicateToolNameError) {
+    console.error('Conflicting tool name:', err.toolName)
+    // Fix: set a unique prefix on one of the clients
+  }
+}
+```
+
+Use a unique `prefix` on each client to avoid collisions — `createMCPClients` does this automatically using the config key.
+
+## Lazy Tool Discovery
+
+Pass `{ lazy: true }` to defer sending tool schemas to the LLM until it explicitly asks for them. This reduces token usage when working with tool-heavy servers.
+
+```ts
+const tools = await mcp.tools({ lazy: true })
+// All tools are marked lazy: true
+```
+
+Works with the pool too:
+
+```ts
+const tools = await pool.tools({ lazy: true })
+```
+
+See [Lazy Tool Discovery](./lazy-tool-discovery) for how the LLM discovers lazy tools at runtime.
+
+## Using MCP with `chat()`
+
+The Quick Start above hands tools to `chat()` manually via `tools: await mcp.tools()` and closes the client yourself. Two follow-on guides cover richer integrations:
+
+> **Let `chat()` own discovery and lifecycle.** Pass live clients and pools to `chat()` via the `mcp` option and it discovers tools and closes connections for you — no `try/finally` per route. See [Managed MCP with `chat()`](./mcp-managed).
+
+> **Resources, prompts, and fully-typed manual tools.** Inject MCP resources and prompts into a `chat()` run, cancel in-flight MCP calls, and spread `toolDefinition`-typed tools. See [Manual MCP: typed tools, resources & prompts](./mcp-manual).
+
+## Error Reference
+
+| Error class | When thrown |
+|---|---|
+| `MCPConnectionError` | `createMCPClient` fails to connect, or a method is called after `close()` |
+| `DuplicateToolNameError` | Two tools have the same name within one client or across the pool |
+| `MCPToolNotFoundError` | A `toolDefinition` name passed to `tools([...defs])` is not found on the server |
+| `MCPTaskRequiredToolError` | A `toolDefinition` passed to `tools([...defs])` names a tool that requires task-based execution (`execution.taskSupport: 'required'`) — such tools are also excluded from `tools()` auto-discovery |
+
+For the `MCPDuplicateToolNameError` thrown when merging tools from multiple sources inside a `chat({ mcp })` run, see [Managed MCP with `chat()`](./mcp-managed#tool-name-collisions).
diff --git a/docs/tools/tools.md b/docs/tools/tools.md
index 356a40e95..7dd8bfab1 100644
--- a/docs/tools/tools.md
+++ b/docs/tools/tools.md
@@ -30,7 +30,7 @@ Tools enable your AI application to:
 ## Framework Support
 
 TanStack AI works with **any** JavaScript framework:
-- Next.js, Express, Remix, Fastify, etc.
+- TanStack Start, Next.js, Express, Remix, Fastify, etc.
 - React, Vue, Solid, Svelte, vanilla JS, etc.
 
 TanStack AI works with any JavaScript framework.
@@ -380,3 +380,4 @@ Once arguments (and approval, if required) are in, the result appears as `part.o
 - [Client Tools](./client-tools) - Learn about client-side tool execution
 - [Tool Approval Flow](./tool-approval) - Implement approval workflows
 - [How Tools Work](./tool-architecture) - Deep dive into the tool architecture
+- [MCP Server Tools](./mcp) - Connect to external MCP servers for additional tools
diff --git a/examples/ts-react-chat/package.json b/examples/ts-react-chat/package.json
index ed6769348..49425e213 100644
--- a/examples/ts-react-chat/package.json
+++ b/examples/ts-react-chat/package.json
@@ -19,6 +19,7 @@
     "@tanstack/ai-gemini": "workspace:*",
     "@tanstack/ai-grok": "workspace:*",
     "@tanstack/ai-groq": "workspace:*",
+    "@tanstack/ai-mcp": "workspace:*",
     "@tanstack/ai-ollama": "workspace:*",
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-openrouter": "workspace:*",
diff --git a/examples/ts-react-chat/src/components/Header.tsx b/examples/ts-react-chat/src/components/Header.tsx
index 7d7b7f333..0e581b321 100644
--- a/examples/ts-react-chat/src/components/Header.tsx
+++ b/examples/ts-react-chat/src/components/Header.tsx
@@ -14,6 +14,7 @@ import {
   Mic,
   MessageSquare,
   Music,
+  Plug,
   Server,
   Video,
   X,
@@ -266,6 +267,19 @@ export default function Header() {
             <Server size={20} />
             <span className="font-medium">Server Function Chat</span>
           </Link>
+
+          <Link
+            to="/mcp-demo"
+            onClick={() => setIsOpen(false)}
+            className="flex items-center gap-3 p-3 rounded-lg hover:bg-gray-800 transition-colors mb-2"
+            activeProps={{
+              className:
+                'flex items-center gap-3 p-3 rounded-lg bg-cyan-600 hover:bg-cyan-700 transition-colors mb-2',
+            }}
+          >
+            <Plug size={20} />
+            <span className="font-medium">MCP Servers</span>
+          </Link>
         </nav>
       </aside>
     </>
diff --git a/examples/ts-react-chat/src/lib/mcp-providers.ts b/examples/ts-react-chat/src/lib/mcp-providers.ts
new file mode 100644
index 000000000..82086c6e6
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/mcp-providers.ts
@@ -0,0 +1,70 @@
+import { openaiText } from '@tanstack/ai-openai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { geminiText } from '@tanstack/ai-gemini'
+import { groqText } from '@tanstack/ai-groq'
+import { openRouterText } from '@tanstack/ai-openrouter'
+
+/**
+ * Providers the MCP demo can route a chat through. MCP tool discovery and
+ * execution are provider-agnostic — the same `mcp: { clients }` config works no
+ * matter which text adapter runs the agent loop. Switching providers here is how
+ * you confirm that (e.g. that Anthropic tool-calling drives the MCP servers just
+ * like OpenAI does).
+ *
+ * Each provider needs its own API key in the environment; the LLM key is
+ * separate from the (keyless) MCP servers.
+ */
+export const MCP_PROVIDERS = [
+  {
+    value: 'openrouter',
+    label: 'OpenRouter',
+    model: 'openai/gpt-5.5',
+    envKey: 'OPENROUTER_API_KEY',
+  },
+  {
+    value: 'openai',
+    label: 'OpenAI',
+    model: 'gpt-5.5',
+    envKey: 'OPENAI_API_KEY',
+  },
+  {
+    value: 'anthropic',
+    label: 'Anthropic',
+    model: 'claude-sonnet-4-6',
+    envKey: 'ANTHROPIC_API_KEY',
+  },
+  {
+    value: 'gemini',
+    label: 'Gemini',
+    model: 'gemini-2.5-flash',
+    envKey: 'GOOGLE_API_KEY',
+  },
+  {
+    value: 'groq',
+    label: 'Groq',
+    model: 'llama-3.3-70b-versatile',
+    envKey: 'GROQ_API_KEY',
+  },
+] as const
+
+export type McpProvider = (typeof MCP_PROVIDERS)[number]['value']
+
+/**
+ * Resolve a request's `provider` (sent from the client via the chat body /
+ * AG-UI forwardedProps) to a configured text adapter. Defaults to OpenAI.
+ */
+export function resolveTextAdapter(provider: unknown) {
+  switch (provider) {
+    case 'openrouter':
+      return openRouterText('openai/gpt-5.5')
+    case 'anthropic':
+      return anthropicText('claude-sonnet-4-6')
+    case 'gemini':
+      return geminiText('gemini-2.5-flash')
+    case 'groq':
+      return groqText('llama-3.3-70b-versatile')
+    case 'openai':
+    default:
+      return openaiText('gpt-5.5')
+  }
+}
diff --git a/examples/ts-react-chat/src/lib/mcp-servers.ts b/examples/ts-react-chat/src/lib/mcp-servers.ts
new file mode 100644
index 000000000..c53ec6e4c
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/mcp-servers.ts
@@ -0,0 +1,29 @@
+import { stdioTransport } from '@tanstack/ai-mcp/stdio'
+import type { Transport } from '@tanstack/ai-mcp'
+
+/**
+ * Keyless official MCP reference servers (run via npx -y; no API keys needed).
+ * Each factory returns a fresh Transport instance — transports are single-use
+ * and must not be shared across requests or reused after close().
+ */
+
+/** @modelcontextprotocol/server-everything — demo tools, resources, and prompts. */
+export const everythingTransport = (): Transport =>
+  stdioTransport({
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-everything'],
+  })
+
+/** @modelcontextprotocol/server-memory — persistent knowledge-graph memory tool. */
+export const memoryTransport = (): Transport =>
+  stdioTransport({
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-memory'],
+  })
+
+/** @modelcontextprotocol/server-sequential-thinking — step-by-step reasoning tool. */
+export const sequentialThinkingTransport = (): Transport =>
+  stdioTransport({
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
+  })
diff --git a/examples/ts-react-chat/src/routeTree.gen.ts b/examples/ts-react-chat/src/routeTree.gen.ts
index 467b07418..83da3a117 100644
--- a/examples/ts-react-chat/src/routeTree.gen.ts
+++ b/examples/ts-react-chat/src/routeTree.gen.ts
@@ -12,6 +12,7 @@ import { Route as rootRouteImport } from './routes/__root'
 import { Route as ThreadsRouteImport } from './routes/threads'
 import { Route as ServerFnChatRouteImport } from './routes/server-fn-chat'
 import { Route as RealtimeRouteImport } from './routes/realtime'
+import { Route as McpDemoRouteImport } from './routes/mcp-demo'
 import { Route as Issue176ToolResultRouteImport } from './routes/issue-176-tool-result'
 import { Route as ImageToolReproRouteImport } from './routes/image-tool-repro'
 import { Route as ImageGenRouteImport } from './routes/image-gen'
@@ -31,6 +32,10 @@ import { Route as ApiTanchatRouteImport } from './routes/api.tanchat'
 import { Route as ApiSummarizeRouteImport } from './routes/api.summarize'
 import { Route as ApiStructuredOutputRouteImport } from './routes/api.structured-output'
 import { Route as ApiStructuredChatRouteImport } from './routes/api.structured-chat'
+import { Route as ApiMcpStatusRouteImport } from './routes/api.mcp-status'
+import { Route as ApiMcpPoolRouteImport } from './routes/api.mcp-pool'
+import { Route as ApiMcpManualRouteImport } from './routes/api.mcp-manual'
+import { Route as ApiMcpChatRouteImport } from './routes/api.mcp-chat'
 import { Route as ApiImageToolReproRouteImport } from './routes/api.image-tool-repro'
 import { Route as ApiImageGenRouteImport } from './routes/api.image-gen'
 import { Route as ExampleGuitarsIndexRouteImport } from './routes/example.guitars/index'
@@ -55,6 +60,11 @@ const RealtimeRoute = RealtimeRouteImport.update({
   path: '/realtime',
   getParentRoute: () => rootRouteImport,
 } as any)
+const McpDemoRoute = McpDemoRouteImport.update({
+  id: '/mcp-demo',
+  path: '/mcp-demo',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const Issue176ToolResultRoute = Issue176ToolResultRouteImport.update({
   id: '/issue-176-tool-result',
   path: '/issue-176-tool-result',
@@ -153,6 +163,26 @@ const ApiStructuredChatRoute = ApiStructuredChatRouteImport.update({
   path: '/api/structured-chat',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiMcpStatusRoute = ApiMcpStatusRouteImport.update({
+  id: '/api/mcp-status',
+  path: '/api/mcp-status',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiMcpPoolRoute = ApiMcpPoolRouteImport.update({
+  id: '/api/mcp-pool',
+  path: '/api/mcp-pool',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiMcpManualRoute = ApiMcpManualRouteImport.update({
+  id: '/api/mcp-manual',
+  path: '/api/mcp-manual',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiMcpChatRoute = ApiMcpChatRouteImport.update({
+  id: '/api/mcp-chat',
+  path: '/api/mcp-chat',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiImageToolReproRoute = ApiImageToolReproRouteImport.update({
   id: '/api/image-tool-repro',
   path: '/api/image-tool-repro',
@@ -200,11 +230,16 @@ export interface FileRoutesByFullPath {
   '/image-gen': typeof ImageGenRoute
   '/image-tool-repro': typeof ImageToolReproRoute
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
+  '/mcp-demo': typeof McpDemoRoute
   '/realtime': typeof RealtimeRoute
   '/server-fn-chat': typeof ServerFnChatRoute
   '/threads': typeof ThreadsRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/image-tool-repro': typeof ApiImageToolReproRoute
+  '/api/mcp-chat': typeof ApiMcpChatRoute
+  '/api/mcp-manual': typeof ApiMcpManualRoute
+  '/api/mcp-pool': typeof ApiMcpPoolRoute
+  '/api/mcp-status': typeof ApiMcpStatusRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
   '/api/summarize': typeof ApiSummarizeRoute
@@ -232,11 +267,16 @@ export interface FileRoutesByTo {
   '/image-gen': typeof ImageGenRoute
   '/image-tool-repro': typeof ImageToolReproRoute
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
+  '/mcp-demo': typeof McpDemoRoute
   '/realtime': typeof RealtimeRoute
   '/server-fn-chat': typeof ServerFnChatRoute
   '/threads': typeof ThreadsRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/image-tool-repro': typeof ApiImageToolReproRoute
+  '/api/mcp-chat': typeof ApiMcpChatRoute
+  '/api/mcp-manual': typeof ApiMcpManualRoute
+  '/api/mcp-pool': typeof ApiMcpPoolRoute
+  '/api/mcp-status': typeof ApiMcpStatusRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
   '/api/summarize': typeof ApiSummarizeRoute
@@ -265,11 +305,16 @@ export interface FileRoutesById {
   '/image-gen': typeof ImageGenRoute
   '/image-tool-repro': typeof ImageToolReproRoute
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
+  '/mcp-demo': typeof McpDemoRoute
   '/realtime': typeof RealtimeRoute
   '/server-fn-chat': typeof ServerFnChatRoute
   '/threads': typeof ThreadsRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/image-tool-repro': typeof ApiImageToolReproRoute
+  '/api/mcp-chat': typeof ApiMcpChatRoute
+  '/api/mcp-manual': typeof ApiMcpManualRoute
+  '/api/mcp-pool': typeof ApiMcpPoolRoute
+  '/api/mcp-status': typeof ApiMcpStatusRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
   '/api/summarize': typeof ApiSummarizeRoute
@@ -299,11 +344,16 @@ export interface FileRouteTypes {
     | '/image-gen'
     | '/image-tool-repro'
     | '/issue-176-tool-result'
+    | '/mcp-demo'
     | '/realtime'
     | '/server-fn-chat'
     | '/threads'
     | '/api/image-gen'
     | '/api/image-tool-repro'
+    | '/api/mcp-chat'
+    | '/api/mcp-manual'
+    | '/api/mcp-pool'
+    | '/api/mcp-status'
     | '/api/structured-chat'
     | '/api/structured-output'
     | '/api/summarize'
@@ -331,11 +381,16 @@ export interface FileRouteTypes {
     | '/image-gen'
     | '/image-tool-repro'
     | '/issue-176-tool-result'
+    | '/mcp-demo'
     | '/realtime'
     | '/server-fn-chat'
     | '/threads'
     | '/api/image-gen'
     | '/api/image-tool-repro'
+    | '/api/mcp-chat'
+    | '/api/mcp-manual'
+    | '/api/mcp-pool'
+    | '/api/mcp-status'
     | '/api/structured-chat'
     | '/api/structured-output'
     | '/api/summarize'
@@ -363,11 +418,16 @@ export interface FileRouteTypes {
     | '/image-gen'
     | '/image-tool-repro'
     | '/issue-176-tool-result'
+    | '/mcp-demo'
     | '/realtime'
     | '/server-fn-chat'
     | '/threads'
     | '/api/image-gen'
     | '/api/image-tool-repro'
+    | '/api/mcp-chat'
+    | '/api/mcp-manual'
+    | '/api/mcp-pool'
+    | '/api/mcp-status'
     | '/api/structured-chat'
     | '/api/structured-output'
     | '/api/summarize'
@@ -396,11 +456,16 @@ export interface RootRouteChildren {
   ImageGenRoute: typeof ImageGenRoute
   ImageToolReproRoute: typeof ImageToolReproRoute
   Issue176ToolResultRoute: typeof Issue176ToolResultRoute
+  McpDemoRoute: typeof McpDemoRoute
   RealtimeRoute: typeof RealtimeRoute
   ServerFnChatRoute: typeof ServerFnChatRoute
   ThreadsRoute: typeof ThreadsRoute
   ApiImageGenRoute: typeof ApiImageGenRoute
   ApiImageToolReproRoute: typeof ApiImageToolReproRoute
+  ApiMcpChatRoute: typeof ApiMcpChatRoute
+  ApiMcpManualRoute: typeof ApiMcpManualRoute
+  ApiMcpPoolRoute: typeof ApiMcpPoolRoute
+  ApiMcpStatusRoute: typeof ApiMcpStatusRoute
   ApiStructuredChatRoute: typeof ApiStructuredChatRoute
   ApiStructuredOutputRoute: typeof ApiStructuredOutputRoute
   ApiSummarizeRoute: typeof ApiSummarizeRoute
@@ -446,6 +511,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof RealtimeRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/mcp-demo': {
+      id: '/mcp-demo'
+      path: '/mcp-demo'
+      fullPath: '/mcp-demo'
+      preLoaderRoute: typeof McpDemoRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/issue-176-tool-result': {
       id: '/issue-176-tool-result'
       path: '/issue-176-tool-result'
@@ -579,6 +651,34 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiStructuredChatRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/mcp-status': {
+      id: '/api/mcp-status'
+      path: '/api/mcp-status'
+      fullPath: '/api/mcp-status'
+      preLoaderRoute: typeof ApiMcpStatusRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/mcp-pool': {
+      id: '/api/mcp-pool'
+      path: '/api/mcp-pool'
+      fullPath: '/api/mcp-pool'
+      preLoaderRoute: typeof ApiMcpPoolRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/mcp-manual': {
+      id: '/api/mcp-manual'
+      path: '/api/mcp-manual'
+      fullPath: '/api/mcp-manual'
+      preLoaderRoute: typeof ApiMcpManualRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/mcp-chat': {
+      id: '/api/mcp-chat'
+      path: '/api/mcp-chat'
+      fullPath: '/api/mcp-chat'
+      preLoaderRoute: typeof ApiMcpChatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/image-tool-repro': {
       id: '/api/image-tool-repro'
       path: '/api/image-tool-repro'
@@ -644,11 +744,16 @@ const rootRouteChildren: RootRouteChildren = {
   ImageGenRoute: ImageGenRoute,
   ImageToolReproRoute: ImageToolReproRoute,
   Issue176ToolResultRoute: Issue176ToolResultRoute,
+  McpDemoRoute: McpDemoRoute,
   RealtimeRoute: RealtimeRoute,
   ServerFnChatRoute: ServerFnChatRoute,
   ThreadsRoute: ThreadsRoute,
   ApiImageGenRoute: ApiImageGenRoute,
   ApiImageToolReproRoute: ApiImageToolReproRoute,
+  ApiMcpChatRoute: ApiMcpChatRoute,
+  ApiMcpManualRoute: ApiMcpManualRoute,
+  ApiMcpPoolRoute: ApiMcpPoolRoute,
+  ApiMcpStatusRoute: ApiMcpStatusRoute,
   ApiStructuredChatRoute: ApiStructuredChatRoute,
   ApiStructuredOutputRoute: ApiStructuredOutputRoute,
   ApiSummarizeRoute: ApiSummarizeRoute,
diff --git a/examples/ts-react-chat/src/routes/api.mcp-chat.ts b/examples/ts-react-chat/src/routes/api.mcp-chat.ts
new file mode 100644
index 000000000..952378bcd
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/api.mcp-chat.ts
@@ -0,0 +1,117 @@
+/**
+ * /api/mcp-chat — Managed MCP lifecycle via chat({ mcp }).
+ *
+ * Demonstrates the chat({ mcp }) prop pattern with MULTIPLE clients:
+ *   1. Two MCP clients are created (everything + memory servers, both keyless).
+ *   2. They are passed to chat() via mcp.clients — chat() handles tool
+ *      discovery and closes both clients when the stream drains (connection: 'close').
+ *   3. No manual client.tools() or client.close() calls needed.
+ *
+ * Uses @modelcontextprotocol/server-everything and @modelcontextprotocol/server-memory
+ * (both keyless, via npx). Only OPENAI_API_KEY is required — no MCP-specific keys needed.
+ */
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  chat,
+  chatParamsFromRequestBody,
+  maxIterations,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { resolveTextAdapter } from '@/lib/mcp-providers'
+import { everythingTransport, memoryTransport } from '@/lib/mcp-servers'
+
+export const Route = createFileRoute('/api/mcp-chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const requestSignal = request.signal
+
+        if (requestSignal.aborted) {
+          return new Response(null, { status: 499 })
+        }
+
+        const abortController = new AbortController()
+
+        let params
+        try {
+          params = await chatParamsFromRequestBody(await request.json())
+        } catch (error) {
+          return new Response(
+            error instanceof Error ? error.message : 'Bad request',
+            { status: 400 },
+          )
+        }
+
+        try {
+          // Connect two keyless MCP servers in parallel.
+          // Prefixes disambiguate tools if both servers expose same-named tools.
+          // OPENAI_API_KEY is used by the LLM adapter (separate from the
+          // keyless MCP server transports which need no credentials).
+          // Settle (don't Promise.all) so that if one server fails to connect,
+          // the sibling that DID connect is closed before rethrowing — no
+          // leaked stdio subprocess. (createMCPClients does this for you;
+          // shown manually here because this route demonstrates individual clients.)
+          const settled = await Promise.allSettled([
+            createMCPClient({
+              transport: everythingTransport(),
+              prefix: 'everything',
+            }),
+            createMCPClient({
+              transport: memoryTransport(),
+              prefix: 'memory',
+            }),
+          ])
+          const rejected = settled.find(
+            (r): r is PromiseRejectedResult => r.status === 'rejected',
+          )
+          if (rejected) {
+            await Promise.allSettled(
+              settled.map((r) =>
+                r.status === 'fulfilled' ? r.value.close() : Promise.resolve(),
+              ),
+            )
+            throw rejected.reason
+          }
+          const clients = settled.flatMap((r) =>
+            r.status === 'fulfilled' ? [r.value] : [],
+          )
+
+          // chat() discovers tools from both clients and closes them when the
+          // stream drains — connection: 'close' (the default; shown explicitly).
+          // The model is encoded in the adapter; do not pass it separately.
+          const stream = chat({
+            adapter: resolveTextAdapter(params.forwardedProps.provider),
+            messages: params.messages,
+            mcp: {
+              clients,
+              connection: 'close',
+            },
+            agentLoopStrategy: maxIterations(20),
+            threadId: params.threadId,
+            runId: params.runId,
+            abortController,
+          })
+
+          return toServerSentEventsResponse(stream, { abortController })
+        } catch (error: any) {
+          console.error('[api.mcp-chat] Error:', {
+            message: error?.message,
+            name: error?.name,
+            stack: error?.stack,
+          })
+          if (error.name === 'AbortError' || abortController.signal.aborted) {
+            return new Response(null, { status: 499 })
+          }
+          return new Response(
+            JSON.stringify({ error: error.message || 'An error occurred' }),
+            {
+              status: 500,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          )
+        }
+      },
+    },
+  },
+})
diff --git a/examples/ts-react-chat/src/routes/api.mcp-manual.ts b/examples/ts-react-chat/src/routes/api.mcp-manual.ts
new file mode 100644
index 000000000..179671d04
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/api.mcp-manual.ts
@@ -0,0 +1,168 @@
+/**
+ * /api/mcp-manual — MANUAL MCP client pattern.
+ *
+ * Demonstrates the fully-manual use-case:
+ *   1. The caller creates the MCP client and owns its lifecycle.
+ *   2. Tools are discovered via client.tools() and spread into chat() explicitly.
+ *   3. Resources and prompts from the server are fetched and injected into the
+ *      conversation as extra context before the user's messages.
+ *   4. The MCP client is closed AFTER the SSE stream fully drains (tool calls
+ *      fire mid-stream, so an earlier close would abort them).
+ *
+ * Uses @modelcontextprotocol/server-everything (keyless, via npx) as the MCP
+ * server. Only OPENAI_API_KEY is required — no MCP-specific API keys needed.
+ */
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  chat,
+  chatParamsFromRequestBody,
+  maxIterations,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import {
+  createMCPClient,
+  mcpPromptToMessages,
+  mcpResourceToContentPart,
+} from '@tanstack/ai-mcp'
+import type { ModelMessage, StreamChunk } from '@tanstack/ai'
+import type { MCPClient } from '@tanstack/ai-mcp'
+import { resolveTextAdapter } from '@/lib/mcp-providers'
+import { everythingTransport } from '@/lib/mcp-servers'
+
+/**
+ * Wrap the chat stream so the MCP client is closed AFTER the stream has fully
+ * drained (or errored). Tool calls fire mid-stream; closing the client earlier
+ * would abort any in-flight MCP tool call.
+ */
+async function* closeMcpOnDrain(
+  stream: AsyncIterable<StreamChunk>,
+  mcp: MCPClient,
+): AsyncGenerator<StreamChunk> {
+  try {
+    for await (const chunk of stream) {
+      yield chunk
+    }
+  } finally {
+    await mcp.close()
+  }
+}
+
+export const Route = createFileRoute('/api/mcp-manual')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        // Capture signal before reading body (it may be aborted after consumption)
+        const requestSignal = request.signal
+
+        if (requestSignal.aborted) {
+          return new Response(null, { status: 499 }) // 499 = Client Closed Request
+        }
+
+        const abortController = new AbortController()
+
+        let params
+        try {
+          params = await chatParamsFromRequestBody(await request.json())
+        } catch (error) {
+          return new Response(
+            error instanceof Error ? error.message : 'Bad request',
+            { status: 400 },
+          )
+        }
+
+        // Held in the outer scope so the catch below can close it on any
+        // error path that happens before the SSE stream takes ownership.
+        let client: MCPClient | undefined
+        try {
+          // --- MCP: create and connect to the everything server (keyless, stdio) ---
+          client = await createMCPClient({
+            transport: everythingTransport(),
+          })
+
+          // Auto-discover all tools from the MCP server.
+          const tools = await client.tools()
+
+          // --- MCP: resources — inject the first resource as context (if any) ---
+          const contextMessages: Array<ModelMessage> = []
+
+          try {
+            const resources = await client.resources()
+            if (resources.length > 0) {
+              // Read the first resource and convert each content block to a ContentPart.
+              const readResult = await client.readResource(resources[0].uri)
+              const parts = readResult.contents.map(mcpResourceToContentPart)
+              if (parts.length > 0) {
+                contextMessages.push({
+                  role: 'user',
+                  content: [
+                    ...parts,
+                    {
+                      type: 'text',
+                      content:
+                        '[MCP resource context injected from server-everything — use this as background information if relevant]',
+                    },
+                  ],
+                })
+              }
+            }
+          } catch {
+            // Resources are optional — proceed without them if unavailable.
+          }
+
+          // --- MCP: prompts — prepend the first available prompt (if any) ---
+          try {
+            const availablePrompts = await client.prompts()
+            if (availablePrompts.length > 0) {
+              const firstPrompt = availablePrompts[0]!
+              const promptResult = await client.getPrompt(firstPrompt.name)
+              const promptMessages = mcpPromptToMessages(promptResult)
+              // Prepend prompt messages before resource context and user messages.
+              contextMessages.unshift(...promptMessages)
+            }
+          } catch {
+            // Prompts are optional — proceed without them if unavailable.
+          }
+
+          // OPENAI_API_KEY is used by the LLM adapter (separate from the
+          // keyless MCP server transport which needs no credentials).
+          // The model is encoded in the adapter; do not pass it separately.
+          const stream = chat({
+            adapter: resolveTextAdapter(params.forwardedProps.provider),
+            messages: [...contextMessages, ...params.messages],
+            tools,
+            agentLoopStrategy: maxIterations(20),
+            threadId: params.threadId,
+            runId: params.runId,
+            abortController,
+          })
+
+          // Close the MCP client only after the SSE stream fully drains.
+          return toServerSentEventsResponse(closeMcpOnDrain(stream, client), {
+            abortController,
+          })
+        } catch (error: any) {
+          // The stream never took ownership of the client — close it here so
+          // the stdio MCP process isn't leaked.
+          if (client) {
+            await client.close().catch(() => undefined)
+          }
+          console.error('[api.mcp-manual] Error:', {
+            message: error?.message,
+            name: error?.name,
+            stack: error?.stack,
+          })
+          if (error.name === 'AbortError' || abortController.signal.aborted) {
+            return new Response(null, { status: 499 })
+          }
+          return new Response(
+            JSON.stringify({ error: error.message || 'An error occurred' }),
+            {
+              status: 500,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          )
+        }
+      },
+    },
+  },
+})
diff --git a/examples/ts-react-chat/src/routes/api.mcp-pool.ts b/examples/ts-react-chat/src/routes/api.mcp-pool.ts
new file mode 100644
index 000000000..4b847b89f
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/api.mcp-pool.ts
@@ -0,0 +1,100 @@
+/**
+ * /api/mcp-pool — createMCPClients pool pattern.
+ *
+ * Demonstrates the createMCPClients() pool API with THREE servers:
+ *   1. A pool of three keyless MCP servers is created in one call.
+ *   2. createMCPClients() auto-prefixes each server's tools with its config key
+ *      (everything_*, memory_*, thinking_*) to prevent name collisions.
+ *   3. The pool is passed to chat() via mcp.clients — chat() owns discovery
+ *      and closes all three connections when the stream drains (connection: 'close').
+ *
+ * Uses @modelcontextprotocol/server-everything, @modelcontextprotocol/server-memory,
+ * and @modelcontextprotocol/server-sequential-thinking (all keyless, via npx).
+ * Only OPENAI_API_KEY is required — no MCP-specific API keys needed.
+ */
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  chat,
+  chatParamsFromRequestBody,
+  maxIterations,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { resolveTextAdapter } from '@/lib/mcp-providers'
+import { createMCPClients } from '@tanstack/ai-mcp'
+import {
+  everythingTransport,
+  memoryTransport,
+  sequentialThinkingTransport,
+} from '@/lib/mcp-servers'
+
+export const Route = createFileRoute('/api/mcp-pool')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const requestSignal = request.signal
+
+        if (requestSignal.aborted) {
+          return new Response(null, { status: 499 })
+        }
+
+        const abortController = new AbortController()
+
+        let params
+        try {
+          params = await chatParamsFromRequestBody(await request.json())
+        } catch (error) {
+          return new Response(
+            error instanceof Error ? error.message : 'Bad request',
+            { status: 400 },
+          )
+        }
+
+        try {
+          // createMCPClients connects all three servers in parallel and
+          // auto-prefixes tools with the config key (everything_*, memory_*,
+          // thinking_*) to prevent collisions.
+          // OPENAI_API_KEY is used by the LLM adapter (separate from the
+          // keyless MCP server transports which need no credentials).
+          const pool = await createMCPClients({
+            everything: { transport: everythingTransport() },
+            memory: { transport: memoryTransport() },
+            thinking: { transport: sequentialThinkingTransport() },
+          })
+
+          // chat() manages discovery and closes all pool connections on drain.
+          // The model is encoded in the adapter; do not pass it separately.
+          const stream = chat({
+            adapter: resolveTextAdapter(params.forwardedProps.provider),
+            messages: params.messages,
+            mcp: {
+              clients: [pool],
+              connection: 'close',
+            },
+            agentLoopStrategy: maxIterations(20),
+            threadId: params.threadId,
+            runId: params.runId,
+            abortController,
+          })
+
+          return toServerSentEventsResponse(stream, { abortController })
+        } catch (error: any) {
+          console.error('[api.mcp-pool] Error:', {
+            message: error?.message,
+            name: error?.name,
+            stack: error?.stack,
+          })
+          if (error.name === 'AbortError' || abortController.signal.aborted) {
+            return new Response(null, { status: 499 })
+          }
+          return new Response(
+            JSON.stringify({ error: error.message || 'An error occurred' }),
+            {
+              status: 500,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          )
+        }
+      },
+    },
+  },
+})
diff --git a/examples/ts-react-chat/src/routes/api.mcp-status.ts b/examples/ts-react-chat/src/routes/api.mcp-status.ts
new file mode 100644
index 000000000..5af82a2e5
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/api.mcp-status.ts
@@ -0,0 +1,83 @@
+/**
+ * /api/mcp-status — connectivity + capability probe for the demo's MCP servers.
+ *
+ * Hit `GET /api/mcp-status` (optionally `?server=everything`) to get a JSON
+ * snapshot of each keyless reference server: whether it connects, and the
+ * tools / resources / prompts it exposes. Handy for validating MCP wiring from
+ * the client without driving a full chat turn.
+ *
+ * Each server is probed with a fresh single-use client that is closed before
+ * responding — this endpoint never keeps connections warm.
+ */
+import { createFileRoute } from '@tanstack/react-router'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import type { Transport } from '@tanstack/ai-mcp'
+import {
+  everythingTransport,
+  memoryTransport,
+  sequentialThinkingTransport,
+} from '@/lib/mcp-servers'
+
+const SERVERS: Array<{ name: string; transport: () => Transport }> = [
+  { name: 'everything', transport: everythingTransport },
+  { name: 'memory', transport: memoryTransport },
+  { name: 'thinking', transport: sequentialThinkingTransport },
+]
+
+interface ServerStatus {
+  name: string
+  connected: boolean
+  tools: Array<string>
+  resources: Array<string>
+  prompts: Array<string>
+  error?: string
+}
+
+async function probe(
+  name: string,
+  makeTransport: () => Transport,
+): Promise<ServerStatus> {
+  try {
+    const client = await createMCPClient({ transport: makeTransport() })
+    try {
+      const tools = (await client.tools()).map((t) => t.name)
+      // Check the advertised capabilities instead of catch-all-ing the list
+      // calls: a server without the capability reports "none", while a real
+      // transport/protocol failure propagates to the outer catch and is
+      // surfaced as a probe error (not silently collapsed to []).
+      const resources = client.capabilities.resources
+        ? (await client.resources()).map((x) => x.uri)
+        : []
+      const prompts = client.capabilities.prompts
+        ? (await client.prompts()).map((x) => x.name)
+        : []
+      return { name, connected: true, tools, resources, prompts }
+    } finally {
+      await client.close()
+    }
+  } catch (error) {
+    return {
+      name,
+      connected: false,
+      tools: [],
+      resources: [],
+      prompts: [],
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+export const Route = createFileRoute('/api/mcp-status')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const only = new URL(request.url).searchParams.get('server')
+        const targets = only ? SERVERS.filter((s) => s.name === only) : SERVERS
+        const servers = await Promise.all(
+          targets.map((s) => probe(s.name, s.transport)),
+        )
+        return Response.json({ servers })
+      },
+    },
+  },
+})
diff --git a/examples/ts-react-chat/src/routes/mcp-demo.tsx b/examples/ts-react-chat/src/routes/mcp-demo.tsx
new file mode 100644
index 000000000..2bc99b5c6
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/mcp-demo.tsx
@@ -0,0 +1,409 @@
+import { useRef, useState } from 'react'
+import { createFileRoute } from '@tanstack/react-router'
+import { Check, Loader2, Send, Square, Wrench } from 'lucide-react'
+import ReactMarkdown from 'react-markdown'
+import rehypeRaw from 'rehype-raw'
+import rehypeSanitize from 'rehype-sanitize'
+import rehypeHighlight from 'rehype-highlight'
+import remarkGfm from 'remark-gfm'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { ThinkingPart } from '@tanstack/ai-react-ui'
+import type { UIMessage } from '@tanstack/ai-react'
+import { MCP_PROVIDERS, type McpProvider } from '@/lib/mcp-providers'
+
+type McpMode = 'manual' | 'chat' | 'pool'
+
+const MODES: Array<{
+  value: McpMode
+  label: string
+  endpoint: string
+  description: string
+}> = [
+  {
+    value: 'manual',
+    label: 'Manual',
+    endpoint: '/api/mcp-manual',
+    description:
+      'Manually spread tools + inject resources/prompts as context before user messages.',
+  },
+  {
+    value: 'chat',
+    label: 'chat({ mcp })',
+    endpoint: '/api/mcp-chat',
+    description:
+      'Pass MCP clients directly to chat(); it handles tool discovery and lifecycle.',
+  },
+  {
+    value: 'pool',
+    label: 'Pool',
+    endpoint: '/api/mcp-pool',
+    description:
+      'createMCPClients() spins up a 3-server pool with auto-prefixed tool names.',
+  },
+]
+
+type ToolCallPart = Extract<UIMessage['parts'][number], { type: 'tool-call' }>
+type ToolResultPart = Extract<
+  UIMessage['parts'][number],
+  { type: 'tool-result' }
+>
+
+function formatValue(value: unknown): string {
+  if (typeof value === 'string') return value
+  try {
+    return JSON.stringify(value, null, 2)
+  } catch {
+    return String(value)
+  }
+}
+
+/** Renders an MCP (or any) tool call: name, arguments, live state, and result. */
+function ToolCallView({ part }: { part: ToolCallPart }) {
+  let args: unknown = part.input
+  if (args === undefined && part.arguments) {
+    try {
+      args = JSON.parse(part.arguments)
+    } catch {
+      args = part.arguments
+    }
+  }
+  const done = part.state === 'complete' || part.output !== undefined
+
+  return (
+    <div className="my-2 overflow-hidden rounded-lg border border-cyan-500/30 bg-cyan-500/5">
+      <div className="flex items-center gap-2 border-b border-cyan-500/20 bg-cyan-500/10 px-3 py-2">
+        <Wrench className="h-3.5 w-3.5 text-cyan-400" />
+        <span className="font-mono text-sm text-cyan-300">{part.name}</span>
+        <span className="ml-auto flex items-center gap-1 text-xs text-gray-400">
+          {done ? (
+            <>
+              <Check className="h-3 w-3 text-green-400" /> done
+            </>
+          ) : (
+            <>
+              <Loader2 className="h-3 w-3 animate-spin" /> {part.state}
+            </>
+          )}
+        </span>
+      </div>
+      <div className="space-y-2 px-3 py-2">
+        <div>
+          <p className="mb-1 text-[10px] uppercase tracking-wide text-gray-500">
+            Arguments
+          </p>
+          <pre className="overflow-x-auto rounded bg-gray-900/60 p-2 text-xs text-gray-300">
+            {formatValue(args ?? {})}
+          </pre>
+        </div>
+        {part.output !== undefined && (
+          <div>
+            <p className="mb-1 text-[10px] uppercase tracking-wide text-gray-500">
+              Result
+            </p>
+            <pre className="max-h-60 overflow-auto rounded bg-gray-900/60 p-2 text-xs text-emerald-200">
+              {formatValue(part.output)}
+            </pre>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+/** Renders a standalone tool-result part (when emitted separately from the call). */
+function ToolResultView({ part }: { part: ToolResultPart }) {
+  return (
+    <div className="my-2 overflow-hidden rounded-lg border border-emerald-500/30 bg-emerald-500/5">
+      <div className="flex items-center gap-2 border-b border-emerald-500/20 bg-emerald-500/10 px-3 py-2">
+        <Check className="h-3.5 w-3.5 text-emerald-400" />
+        <span className="text-sm text-emerald-300">Tool result</span>
+        {part.state === 'error' && (
+          <span className="ml-auto text-xs text-red-400">error</span>
+        )}
+      </div>
+      <pre className="max-h-60 overflow-auto px-3 py-2 text-xs text-emerald-200">
+        {part.error ?? formatValue(part.content)}
+      </pre>
+    </div>
+  )
+}
+
+function Messages({ messages }: { messages: Array<UIMessage> }) {
+  const messagesContainerRef = useRef<HTMLDivElement>(null)
+
+  const visibleMessages = messages.filter((message) =>
+    message.parts.some(
+      (part) =>
+        (part.type === 'text' && part.content.trim()) ||
+        part.type === 'thinking' ||
+        part.type === 'tool-call' ||
+        part.type === 'tool-result',
+    ),
+  )
+
+  if (!visibleMessages.length) {
+    return (
+      <div className="flex-1 overflow-y-auto px-4 py-8">
+        <div className="max-w-2xl mx-auto text-center">
+          <p className="text-gray-400 text-sm">
+            Select a mode above and send a message to try it out.
+          </p>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div
+      ref={messagesContainerRef}
+      className="flex-1 overflow-y-auto px-4 py-4"
+    >
+      {visibleMessages.map((message) => (
+        <div
+          key={message.id}
+          className={`p-4 rounded-lg mb-2 ${
+            message.role === 'assistant'
+              ? 'bg-linear-to-r from-orange-500/5 to-red-600/5'
+              : 'bg-transparent'
+          }`}
+        >
+          <div className="flex items-start gap-4">
+            {message.role === 'assistant' ? (
+              <div className="w-8 h-8 rounded-lg bg-linear-to-r from-orange-500 to-red-600 flex items-center justify-center text-sm font-medium text-white shrink-0">
+                AI
+              </div>
+            ) : (
+              <div className="w-8 h-8 rounded-lg bg-gray-700 flex items-center justify-center text-sm font-medium text-white shrink-0">
+                U
+              </div>
+            )}
+            <div className="flex-1 min-w-0">
+              {message.parts.map((part, index) => {
+                if (part.type === 'thinking') {
+                  const isComplete = message.parts
+                    .slice(index + 1)
+                    .some((p) => p.type === 'text')
+                  return (
+                    <div key={`thinking-${index}`} className="mt-2 mb-2">
+                      <ThinkingPart
+                        content={part.content}
+                        isComplete={isComplete}
+                        className="p-4 bg-gray-800/50 border border-gray-700/50 rounded-lg"
+                      />
+                    </div>
+                  )
+                }
+
+                if (part.type === 'text' && part.content) {
+                  return (
+                    <div
+                      key={`text-${index}`}
+                      className="text-white prose dark:prose-invert max-w-none"
+                    >
+                      <ReactMarkdown
+                        rehypePlugins={[
+                          rehypeRaw,
+                          rehypeSanitize,
+                          rehypeHighlight,
+                        ]}
+                        remarkPlugins={[remarkGfm]}
+                      >
+                        {part.content}
+                      </ReactMarkdown>
+                    </div>
+                  )
+                }
+
+                if (part.type === 'tool-call') {
+                  return <ToolCallView key={`tool-${index}`} part={part} />
+                }
+
+                if (part.type === 'tool-result') {
+                  return <ToolResultView key={`result-${index}`} part={part} />
+                }
+
+                return null
+              })}
+            </div>
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+function ChatSurface({
+  endpoint,
+  threadId,
+  provider,
+}: {
+  endpoint: string
+  threadId: string
+  provider: McpProvider
+}) {
+  const { messages, sendMessage, isLoading, error, stop } = useChat({
+    // A stable threadId is sent to the server (AG-UI `RunAgentInput.threadId`)
+    // and used to group this conversation's runs in the TanStack AI devtools.
+    threadId,
+    connection: fetchServerSentEvents(endpoint),
+    // `provider` is forwarded to the route (AG-UI forwardedProps); the route
+    // resolves it to the matching text adapter. MCP works the same regardless.
+    body: { provider },
+  })
+
+  const [input, setInput] = useState('')
+
+  const handleSend = () => {
+    if (!input.trim()) return
+    sendMessage(input.trim())
+    setInput('')
+  }
+
+  return (
+    <div className="flex flex-col flex-1 min-h-0">
+      <Messages messages={messages} />
+
+      {error && (
+        <div className="mx-4 mt-2 p-3 bg-red-500/10 border border-red-500/30 rounded-lg text-red-400 text-sm">
+          {error.message}
+        </div>
+      )}
+
+      <div className="border-t border-orange-500/10 bg-gray-900/80 backdrop-blur-sm">
+        <div className="w-full px-4 py-3 space-y-2">
+          {isLoading && (
+            <div className="flex items-center justify-center">
+              <button
+                onClick={stop}
+                className="px-4 py-2 bg-red-600 hover:bg-red-700 text-white rounded-lg text-sm font-medium transition-colors flex items-center gap-2"
+              >
+                <Square className="w-4 h-4 fill-current" />
+                Stop
+              </button>
+            </div>
+          )}
+          <div className="relative flex items-end gap-2">
+            <div className="flex-1 relative">
+              <textarea
+                value={input}
+                onChange={(e) => setInput(e.target.value)}
+                placeholder="Ask the MCP servers something..."
+                className="w-full rounded-lg border border-orange-500/20 bg-gray-800/50 pl-4 pr-12 py-3 text-sm text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-orange-500/50 focus:border-transparent resize-none overflow-hidden shadow-lg"
+                rows={1}
+                style={{ minHeight: '44px', maxHeight: '200px' }}
+                disabled={isLoading}
+                onInput={(e) => {
+                  const target = e.target as HTMLTextAreaElement
+                  target.style.height = 'auto'
+                  target.style.height =
+                    Math.min(target.scrollHeight, 200) + 'px'
+                }}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' && !e.shiftKey && input.trim()) {
+                    e.preventDefault()
+                    handleSend()
+                  }
+                }}
+              />
+              <button
+                onClick={handleSend}
+                disabled={!input.trim() || isLoading}
+                className="absolute right-2 top-1/2 -translate-y-1/2 p-2 text-orange-500 hover:text-orange-400 disabled:text-gray-500 transition-colors focus:outline-none"
+              >
+                <Send className="w-4 h-4" />
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function McpDemoPage() {
+  const [mode, setMode] = useState<McpMode>('manual')
+  const [provider, setProvider] = useState<McpProvider>('openrouter')
+
+  const selectedMode = MODES.find((m) => m.value === mode)!
+  const selectedProvider = MCP_PROVIDERS.find((p) => p.value === provider)!
+
+  return (
+    <div className="flex flex-col h-[calc(100vh-72px)] bg-gray-900">
+      {/* Header / mode + provider selectors */}
+      <div className="border-b border-orange-500/20 bg-gray-800 px-4 py-3 shrink-0">
+        <p className="text-xs text-gray-400 mb-3">
+          These chat against keyless MCP reference servers (server-everything /
+          -memory / -sequential-thinking) spawned via stdio. The MCP servers
+          need no keys — but the selected LLM provider does (set{' '}
+          <code className="text-gray-300">{selectedProvider.envKey}</code> in
+          your environment). First run downloads the servers via npx.
+        </p>
+
+        <div className="flex gap-2 flex-wrap">
+          {MODES.map((m) => (
+            <label
+              key={m.value}
+              className={`flex items-center gap-2 px-3 py-2 rounded-lg border cursor-pointer transition-colors text-sm ${
+                mode === m.value
+                  ? 'border-orange-500 bg-orange-500/10 text-orange-400'
+                  : 'border-gray-600 bg-gray-700/50 text-gray-300 hover:border-orange-500/50'
+              }`}
+            >
+              <input
+                type="radio"
+                name="mcp-mode"
+                value={m.value}
+                checked={mode === m.value}
+                onChange={() => setMode(m.value)}
+                className="sr-only"
+              />
+              <span className="font-medium">{m.label}</span>
+            </label>
+          ))}
+        </div>
+
+        {/* Provider selector — MCP tool discovery/execution is provider-agnostic */}
+        <div className="mt-3 flex items-center gap-2 flex-wrap">
+          <span className="text-xs uppercase tracking-wide text-gray-500">
+            Provider
+          </span>
+          {MCP_PROVIDERS.map((p) => (
+            <label
+              key={p.value}
+              className={`flex items-center gap-2 px-3 py-1.5 rounded-lg border cursor-pointer transition-colors text-sm ${
+                provider === p.value
+                  ? 'border-cyan-500 bg-cyan-500/10 text-cyan-300'
+                  : 'border-gray-600 bg-gray-700/50 text-gray-300 hover:border-cyan-500/50'
+              }`}
+            >
+              <input
+                type="radio"
+                name="mcp-provider"
+                value={p.value}
+                checked={provider === p.value}
+                onChange={() => setProvider(p.value)}
+                className="sr-only"
+              />
+              <span className="font-medium">{p.label}</span>
+              <span className="text-xs text-gray-500">{p.model}</span>
+            </label>
+          ))}
+        </div>
+
+        <p className="mt-2 text-xs text-gray-400">{selectedMode.description}</p>
+      </div>
+
+      {/* Remount the chat surface on mode/provider change so each combo gets a fresh session */}
+      <ChatSurface
+        key={`${mode}-${provider}`}
+        endpoint={selectedMode.endpoint}
+        threadId={`mcp-${mode}-${provider}`}
+        provider={provider}
+      />
+    </div>
+  )
+}
+
+export const Route = createFileRoute('/mcp-demo')({
+  component: McpDemoPage,
+})
diff --git a/examples/ts-react-chat/src/routes/threads.tsx b/examples/ts-react-chat/src/routes/threads.tsx
index 32e88fe70..5ab90294e 100644
--- a/examples/ts-react-chat/src/routes/threads.tsx
+++ b/examples/ts-react-chat/src/routes/threads.tsx
@@ -352,7 +352,8 @@ function ThreadsRoute() {
 
 const CHAT_BODY = { provider: 'openrouter', model: 'openai/gpt-5.1' } as const
 
-const MARKDOWN_PLUGINS = [rehypeRaw, rehypeSanitize, rehypeHighlight, remarkGfm]
+const REHYPE_PLUGINS = [rehypeRaw, rehypeSanitize, rehypeHighlight]
+const REMARK_PLUGINS = [remarkGfm]
 
 /** Render a single UIMessage part: reasoning, text, approval prompt, or guitar card. */
 function MessagePart({
@@ -386,7 +387,10 @@ function MessagePart({
   if (part.type === 'text' && part.content) {
     return (
       <div className="prose prose-invert max-w-none text-white">
-        <ReactMarkdown rehypePlugins={MARKDOWN_PLUGINS}>
+        <ReactMarkdown
+          rehypePlugins={REHYPE_PLUGINS}
+          remarkPlugins={REMARK_PLUGINS}
+        >
           {part.content}
         </ReactMarkdown>
       </div>
diff --git a/knip.json b/knip.json
index 67ae81303..a5e8a03e1 100644
--- a/knip.json
+++ b/knip.json
@@ -8,6 +8,7 @@
   ],
   "ignore": [
     "scripts/**",
+    "**/*.test-d.ts",
     "packages/ai-code-mode-skills/test-cli/**",
     ".claude/worktrees/**",
     "packages/ai-openai/live-tests/**",
diff --git a/packages/ai-mcp/README.md b/packages/ai-mcp/README.md
new file mode 100644
index 000000000..946b1867b
--- /dev/null
+++ b/packages/ai-mcp/README.md
@@ -0,0 +1,50 @@
+# @tanstack/ai-mcp
+
+Host-side Model Context Protocol (MCP) client for TanStack AI.
+
+Discover and run MCP server tools, resources, and prompts inside any TanStack AI `chat()` / agent loop — across any provider adapter — with optional generated TypeScript types (typed tool names and pool keys).
+
+## Features
+
+- `createMCPClient({ transport })` — connect to a single MCP server (Streamable HTTP, SSE, or stdio)
+- `createMCPClients({ ... })` — connect to many servers at once with auto-prefix collision avoidance
+- Auto-discovery (`client.tools()`) or explicit typed binding (`client.tools([toolDefinition(...)])`)
+- `@tanstack/ai-mcp/stdio` subpath — Node-only stdio transport, isolated so edge bundles stay clean
+- Bundled `tanstack-ai-mcp generate` CLI — introspects live servers and emits TypeScript types for `createMCPClient<MyServer>()`
+- `[Symbol.asyncDispose]` support — use `await using` for automatic cleanup
+
+## Installation
+
+```bash
+pnpm add @tanstack/ai-mcp @modelcontextprotocol/sdk
+```
+
+## Quick Start
+
+```ts
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai/adapters'
+
+const mcp = await createMCPClient({
+  transport: { type: 'http', url: 'https://your-mcp-server.com/mcp' },
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages: [{ role: 'user', content: 'What is the weather in Brooklyn?' }],
+  tools: await mcp.tools(),
+})
+
+// Tools execute lazily while the stream is consumed — close only after
+// the stream is fully drained (or hand lifecycle to chat() via the `mcp` option).
+for await (const chunk of stream) {
+  // handle StreamChunks, or return toServerSentEventsResponse(stream) instead
+}
+
+await mcp.close()
+```
+
+## License
+
+MIT
diff --git a/packages/ai-mcp/package.json b/packages/ai-mcp/package.json
new file mode 100644
index 000000000..ad4c4f72f
--- /dev/null
+++ b/packages/ai-mcp/package.json
@@ -0,0 +1,62 @@
+{
+  "name": "@tanstack/ai-mcp",
+  "version": "0.0.1",
+  "description": "Host-side Model Context Protocol client for TanStack AI: discover and run MCP server tools, resources, and prompts in any adapter's chat() loop, with generated end-to-end types.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-mcp"
+  },
+  "keywords": [
+    "ai",
+    "mcp",
+    "model-context-protocol",
+    "tanstack",
+    "tools",
+    "typescript"
+  ],
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "bin": {
+    "tanstack-ai-mcp": "./dist/bin/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./stdio": {
+      "types": "./dist/esm/stdio.d.ts",
+      "import": "./dist/esm/stdio.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build && tsup --config tsup.bin.config.ts",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:coverage": "vitest run --coverage",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@tanstack/ai": "workspace:*"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.14",
+    "jiti": "^2.4.2",
+    "json-schema-to-typescript": "^15.0.4",
+    "tsup": "^8.5.1",
+    "vite": "^7.3.3",
+    "zod": "^4.2.0"
+  }
+}
diff --git a/packages/ai-mcp/skills/ai-mcp/SKILL.md b/packages/ai-mcp/skills/ai-mcp/SKILL.md
new file mode 100644
index 000000000..d601802bd
--- /dev/null
+++ b/packages/ai-mcp/skills/ai-mcp/SKILL.md
@@ -0,0 +1,702 @@
+---
+name: ai-mcp
+description: >
+  Host-side Model Context Protocol (MCP) client for TanStack AI: connect to
+  external MCP servers, discover and run their tools inside any adapter's
+  chat() loop, read resources and prompts, generate TypeScript types (typed tool names/pool keys)
+  with the bundled CLI, and manage lifecycle with close()/await using.
+type: sub-skill
+library: tanstack-ai
+library_version: '0.10.0'
+sources:
+  - 'TanStack/ai:docs/tools/mcp.md'
+  - 'TanStack/ai:packages/ai-mcp/src/client.ts'
+  - 'TanStack/ai:packages/ai-mcp/src/pool.ts'
+  - 'TanStack/ai:packages/ai-mcp/src/resources.ts'
+  - 'TanStack/ai:packages/ai-mcp/src/transport.ts'
+---
+
+# `@tanstack/ai-mcp`
+
+This skill covers the `@tanstack/ai-mcp` package. Read `ai-core/tool-calling/SKILL.md`
+first — MCP tools flow into `chat()` the same way hand-written tools do.
+
+## When to use this package
+
+Use `@tanstack/ai-mcp` when:
+
+- A third-party MCP server exposes tools you want an agent or chat loop to call.
+- You want to read MCP server resources (files, text, data) or prompts into a
+  `chat()` message list.
+- You want generated TypeScript types for an external MCP server's tool
+  signatures (via the bundled `generate` CLI).
+- You are running tool execution on the server side and want to connect to MCP
+  servers with HTTP (Streamable HTTP or SSE) or stdio transports.
+
+Do NOT use this package for browser/client-side code — MCP connections are
+server-side only.
+
+## Install
+
+```bash
+pnpm add @tanstack/ai-mcp
+```
+
+The package has two subpath exports:
+
+- `.` — main client API (`createMCPClient`, `createMCPClients`, converters, types)
+- `./stdio` — Node-only stdio transport factory (`stdioTransport`); import it
+  separately so edge bundles stay clean
+
+## `createMCPClient` — single server
+
+```typescript
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+const client = await createMCPClient({
+  transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+  prefix: 'weather', // optional: prefixes all tool names (e.g. 'weather_get_forecast')
+  name: 'my-app', // optional: client identity sent to the server
+})
+```
+
+`createMCPClient` connects immediately and returns an `MCPClient`. Throws
+`MCPConnectionError` if the connection fails.
+
+### Transports
+
+#### Streamable HTTP (default for internet-facing servers)
+
+```typescript
+const client = await createMCPClient({
+  transport: {
+    type: 'http',
+    url: 'https://mcp.example.com/mcp',
+    headers: { Authorization: 'Bearer sk-...' },
+  },
+})
+```
+
+#### SSE
+
+```typescript
+const client = await createMCPClient({
+  transport: {
+    type: 'sse',
+    url: 'https://mcp.example.com/sse',
+    headers: { Authorization: 'Bearer sk-...' },
+  },
+})
+```
+
+#### stdio (Node-only — import from `/stdio` subpath)
+
+```typescript
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { stdioTransport } from '@tanstack/ai-mcp/stdio'
+
+const client = await createMCPClient({
+  transport: stdioTransport({
+    command: 'npx',
+    args: ['-y', 'my-mcp-server'],
+    env: { API_KEY: process.env.API_KEY ?? '' },
+  }),
+})
+```
+
+#### Custom transport (escape hatch)
+
+Pass any SDK `Transport` instance directly:
+
+```typescript
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
+
+const [clientTransport] = InMemoryTransport.createLinkedPair()
+const client = await createMCPClient({ transport: clientTransport })
+```
+
+### Authentication
+
+Two levels:
+
+- **Static tokens** — pass `headers` on the `http`/`sse` config (sent with
+  every request): `headers: { Authorization: 'Bearer ...' }`.
+- **OAuth 2.1 (MCP authorization spec)** — pass `authProvider` on the
+  `http`/`sse` config. It accepts any `OAuthClientProvider` from
+  `@modelcontextprotocol/sdk/client/auth.js`; the SDK transport attaches
+  tokens, refreshes them, and retries on 401.
+
+```typescript
+import { createMCPClient } from '@tanstack/ai-mcp'
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js'
+
+declare const myOAuthProvider: OAuthClientProvider // backed by stored tokens
+
+const client = await createMCPClient({
+  transport: {
+    type: 'http',
+    url: 'https://mcp.example.com/mcp',
+    authProvider: myOAuthProvider,
+  },
+})
+```
+
+Caveat: interactive authorization-code flows need `transport.finishAuth(code)`,
+and `createMCPClient` does not expose its internal transport. For redirect
+flows, construct the `StreamableHTTPClientTransport` yourself with the
+`authProvider`, keep a reference, call `finishAuth(code)` in the OAuth
+callback route, then pass the transport via the escape hatch above. For
+server-side providers backed by pre-provisioned/refreshable tokens, the
+config form is sufficient.
+
+## Three type-safety modes
+
+### Mode 1 — Auto-discovery (no types needed)
+
+`client.tools()` lists every tool the server exposes. Args are typed `unknown`
+at compile time but the tool's JSON Schema is forwarded to the LLM.
+
+```typescript
+const tools = await client.tools()
+// tools: ServerTool[]  (args unknown)
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  tools,
+})
+```
+
+Use `{ lazy: true }` to defer schema sending via the existing `LazyToolManager`:
+
+```typescript
+const tools = await client.tools({ lazy: true })
+```
+
+### Mode 2 — Typed via `toolDefinition` instances
+
+Pass bare `toolDefinition()` instances (no `.server()` call) to `client.tools([...])`.
+The MCP client binds a `callTool` proxy as the execute function while
+input/output validation and TypeScript types come from the definitions' Zod schemas.
+Only the named tools are returned (allowlist = the definitions' `name`s).
+Throws `MCPToolNotFoundError` if the server does not expose a tool with that name.
+
+```typescript
+import { toolDefinition } from '@tanstack/ai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { z } from 'zod'
+
+const getWeatherDef = toolDefinition({
+  name: 'get_weather',
+  description: 'Current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+  outputSchema: z.object({ temperature: z.number(), conditions: z.string() }),
+})
+
+const client = await createMCPClient({
+  transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+})
+
+// Returns MappedServerTools<typeof defs> — fully typed per definition.
+const tools = await client.tools([getWeatherDef])
+```
+
+### Mode 3 — Generated types (via `generate` CLI)
+
+Run `npx @tanstack/ai-mcp generate` to introspect live servers and emit a
+`ServerDescriptor` interface per server. Pass the generated interface as the
+generic to `createMCPClient<WeatherServer>(...)` to narrow discovered tool
+names to the server's literals (args stay untyped — use Mode 2 for typed args).
+
+See the "Codegen CLI" section below for details.
+
+## Lifecycle
+
+**The caller owns the lifecycle.** `chat()` never closes the client.
+
+Tools execute lazily while the response stream is consumed — close only after
+the stream is drained. In a streaming route handler, `try/finally` around the
+`return` (or `await using` at function scope) closes the client before the
+body streams; use a middleware terminal hook there instead (see Common
+Mistakes below).
+
+```typescript
+// Option 1: middleware terminal hooks (streaming route handlers)
+const client = await createMCPClient({
+  transport: { type: 'http', url: '...' },
+})
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  tools: await client.tools(),
+  middleware: [
+    {
+      name: 'mcp-close',
+      onFinish: () => client.close(),
+      onAbort: () => client.close(),
+      onError: () => client.close(),
+    },
+  ],
+})
+return toServerSentEventsResponse(stream)
+
+// Option 2: explicit close after in-scope consumption
+const client = await createMCPClient({
+  transport: { type: 'http', url: '...' },
+})
+try {
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages,
+    tools: await client.tools(),
+  })
+  for await (const chunk of stream) {
+    // stream fully consumed inside this block
+  }
+} finally {
+  await client.close()
+}
+
+// Option 3: await using (TypeScript 5.2+ with Symbol.asyncDispose) —
+// same rule: consume the stream before the scope exits.
+await using client = await createMCPClient({
+  transport: { type: 'http', url: '...' },
+})
+// ... consume the stream in this scope; close() runs at scope exit
+```
+
+## `chat({ mcp })` — discovery + lifecycle in one prop
+
+Rather than calling `client.tools()` and `client.close()` yourself, pass the
+`mcp` option to `chat()` and let it manage the full lifecycle.
+
+```typescript
+// ChatMCPOptions shape:
+// mcp: {
+//   clients: Array<MCPClient | MCPClients>,
+//   connection?: 'close' | 'keep-alive',  // default: 'close'
+//   lazyTools?: boolean,
+//   onDiscoveryError?: (error: unknown, source) => void,
+// }
+```
+
+**Behavior:**
+
+- `chat()` calls `.tools()` on every entry in `clients` at run start and merges
+  all results into the tool list.
+- `lazyTools: true` is forwarded to `tools({ lazy: true })`.
+- `connection: 'close'` (default) — each client is closed when the run ends
+  (after the agent loop completes and the stream is drained). With
+  `'keep-alive'`, `chat()` never closes the clients — the caller owns their
+  lifecycle (keep connections warm across requests).
+- `onDiscoveryError`: throw (or re-throw) to abort the entire call; return
+  normally to skip that source and continue. Omitting the handler re-throws
+  (fail-fast).
+
+**When to use `mcp` vs. the tools spread:**
+
+| Approach                                                | Use when                                                                  |
+| ------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `chat({ mcp: { clients: [...] } })`                     | Convenience: discovery + lifecycle handled for you; untyped args are fine |
+| `tools: [...await client.tools([toolDefinition(...)])]` | Fully-typed args/results via Zod schemas (`toolDefinition` mode)          |
+
+**Server-side example:**
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        const mcpClient = await createMCPClient({
+          transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+        })
+
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          mcp: {
+            clients: [mcpClient],
+            connection: 'keep-alive', // chat() won't close it — reuse across requests
+            onDiscoveryError: (err, source) => {
+              console.warn('MCP discovery failed for source, skipping:', err)
+              // returning skips this source; throw to fail the whole call fast
+            },
+          },
+        })
+
+        return toServerSentEventsResponse(stream)
+        // connection: 'keep-alive' — chat() never closes mcpClient; it stays warm for the next request.
+      },
+    },
+  },
+})
+```
+
+You can also pass an `MCPClients` pool directly:
+
+```typescript
+const pool = await createMCPClients({
+  github: { transport: { type: 'http', url: 'https://mcp.github.com/mcp' } },
+  linear: { transport: { type: 'http', url: 'https://mcp.linear.app/mcp' } },
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  mcp: { clients: [pool], connection: 'keep-alive' },
+})
+```
+
+## `createMCPClients` — multiple servers
+
+Connect to many MCP servers in parallel. Each config key becomes the default
+prefix for that server's tools, preventing name collisions across servers.
+
+```typescript
+import { createMCPClients } from '@tanstack/ai-mcp'
+
+await using pool = await createMCPClients({
+  github: { transport: { type: 'http', url: 'https://mcp.github.com/mcp' } },
+  linear: { transport: { type: 'http', url: 'https://mcp.linear.app/mcp' } },
+})
+
+// Tool names auto-prefixed: 'github_search_repos', 'linear_create_issue', etc.
+const tools = await pool.tools()
+
+// Forward lazy flag to every server:
+const lazyTools = await pool.tools({ lazy: true })
+
+// Per-server typed access:
+const githubTools = await pool.clients.github.tools()
+```
+
+`createMCPClients` connects in parallel, closes already-connected clients if
+any connection fails (no leaks), and throws `MCPConnectionError` naming the
+failed server(s).
+
+Override or disable prefixing:
+
+```typescript
+await using pool = await createMCPClients({
+  github: { transport: { ... }, prefix: 'gh' },    // 'gh_search_repos'
+  linear: { transport: { ... }, prefix: '' },        // 'create_issue' (no prefix)
+})
+```
+
+## Abort signal — cancelling in-flight MCP calls
+
+MCP tool calls are automatically cancelled when the chat run's `AbortController`
+fires (e.g. client disconnect, server abort). The `abortSignal` is threaded
+through `ToolExecutionContext` into every `callTool` call with no extra code.
+
+You can also read it in a hand-written server tool that wraps an MCP call:
+
+```typescript
+const myTool = myDef.server(async (args, ctx) => {
+  // Forward to any async work that accepts an AbortSignal.
+  const result = await fetch('https://slow.api/data', {
+    signal: ctx?.abortSignal,
+  })
+  return result.json()
+})
+```
+
+## Resources
+
+```typescript
+// List all resources the server exposes.
+const resources = await client.resources()
+
+// Read a specific resource by URI.
+const resource = await client.readResource(resources[0].uri)
+
+// Convert one content block to a TanStack ContentPart.
+import { mcpResourceToContentPart } from '@tanstack/ai-mcp'
+
+const part = mcpResourceToContentPart(resource.contents[0])
+// part: ContentPart  (type: 'text' always for v1)
+```
+
+Inject resources into a chat turn:
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { createMCPClient, mcpResourceToContentPart } from '@tanstack/ai-mcp'
+
+const client = await createMCPClient({
+  transport: { type: 'http', url: '...' },
+})
+const resource = await client.readResource('file:///project/README.md')
+const parts = resource.contents.map(mcpResourceToContentPart)
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages: [
+    {
+      role: 'user',
+      content: [
+        ...parts,
+        { type: 'text', content: 'Summarize this document.' },
+      ],
+    },
+  ],
+})
+```
+
+## Prompts
+
+```typescript
+// List prompts the server exposes.
+const prompts = await client.prompts()
+
+// Get a prompt (with optional arguments).
+const prompt = await client.getPrompt('review_code', { language: 'TypeScript' })
+
+// Convert to TanStack ModelMessage[] for use in chat().
+import { mcpPromptToMessages } from '@tanstack/ai-mcp'
+
+const messages = mcpPromptToMessages(prompt)
+// messages: ModelMessage[]  (role: 'user' | 'assistant')
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages: [...messages, ...userMessages],
+})
+```
+
+## Codegen CLI
+
+Generate TypeScript types (typed tool names and pool keys) by introspecting live MCP servers.
+
+**1. Create `mcp.config.ts` at your project root:**
+
+```typescript
+import { defineConfig } from '@tanstack/ai-mcp'
+
+export default defineConfig({
+  servers: {
+    github: {
+      transport: { type: 'http', url: 'https://mcp.github.com/mcp' },
+      // prefix must match the runtime createMCPClient({ prefix }) value
+    },
+  },
+  outFile: './src/mcp-types.generated.ts',
+})
+```
+
+**2. Run the generator:**
+
+```bash
+npx @tanstack/ai-mcp generate
+```
+
+This connects to each server, lists its tools/resources/prompts, converts JSON
+Schemas to TypeScript, and writes one `interface <Name>Server extends ServerDescriptor`
+per server plus a combined `interface MCPServers` for pool typing.
+
+**3. Use the generated types:**
+
+```typescript
+// Single server — narrows tools() return to descriptor-keyed tool names.
+import type { GithubServer } from './src/mcp-types.generated'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+const client = await createMCPClient<GithubServer>({
+  transport: { type: 'http', url: 'https://mcp.github.com/mcp' },
+})
+const tools = await client.tools() // typed to GithubServer's tool names
+
+// Multiple servers via the generated MCPServers map.
+import type { MCPServers } from './src/mcp-types.generated'
+
+const pool = await createMCPClients<MCPServers>({
+  github: { transport: { type: 'http', url: 'https://mcp.github.com/mcp' } },
+})
+// pool.clients.github is MCPClient<GithubServer>
+// missing/extra keys are a compile error
+```
+
+Codegen deps (`json-schema-to-typescript`, `jiti`) are bundled into the CLI bin
+and do NOT appear in the library's runtime dependency graph.
+
+## Error classes
+
+- `MCPConnectionError` — thrown when a server connection fails or when calling
+  methods after `close()`.
+- `MCPToolNotFoundError` — thrown from `client.tools([defs])` when a definition's
+  `name` is not exposed by the server.
+- `MCPTaskRequiredToolError` — thrown from `client.tools([defs])` when the named
+  tool declares `execution.taskSupport: 'required'` (experimental MCP tasks).
+  Such tools only run via the SDK's `tasks/callToolStream` flow, which
+  `@tanstack/ai-mcp` does not support yet; they are silently excluded from
+  `tools()` auto-discovery for the same reason.
+- `DuplicateToolNameError` — thrown by a single pool's own `tools()` when two
+  tools within that pool share the same name (same server or pool clients with no
+  prefix). Exported from `@tanstack/ai-mcp`.
+- `MCPDuplicateToolNameError` — thrown by `chat()` when tools from separate
+  `mcp.clients` entries collide after merging. Exported from `@tanstack/ai`
+  (not `@tanstack/ai-mcp`), so users can `instanceof` it at the `chat()` call site.
+
+```typescript
+import {
+  MCPConnectionError,
+  MCPToolNotFoundError,
+  MCPTaskRequiredToolError,
+  DuplicateToolNameError,
+} from '@tanstack/ai-mcp'
+
+import { MCPDuplicateToolNameError } from '@tanstack/ai'
+```
+
+## Complete server-route example
+
+```typescript
+// src/routes/api.chat.ts
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClients } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        const pool = await createMCPClients({
+          github: {
+            transport: { type: 'http', url: 'https://mcp.github.com/mcp' },
+          },
+          linear: {
+            transport: {
+              type: 'http',
+              url: 'https://mcp.linear.app/mcp',
+              headers: {
+                Authorization: `Bearer ${process.env.LINEAR_KEY ?? ''}`,
+              },
+            },
+          },
+        })
+
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          tools: await pool.tools(),
+          // Close after the run ends — tools execute while the response streams,
+          // so `await using` / try-finally would close the pool too early here.
+          middleware: [
+            {
+              name: 'mcp-close',
+              onFinish: () => pool.close(),
+              onAbort: () => pool.close(),
+              onError: () => pool.close(),
+            },
+          ],
+        })
+
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+## Common Mistakes
+
+### a. HIGH: closing the client before the stream finishes
+
+`chat()` executes tools lazily as the model calls them during streaming.
+If you close the MCP client before the response stream is fully consumed,
+in-flight tool calls will fail.
+
+Wrong:
+
+```typescript
+const tools = await client.tools()
+const stream = chat({ adapter, messages, tools })
+await client.close() // closes before the stream runs tools
+return toServerSentEventsResponse(stream)
+```
+
+This includes `try/finally` around the `return`, and `await using` at function
+scope — both close before the returned `Response` body streams.
+
+Correct — close in middleware terminal hooks (exactly one of
+`onFinish`/`onAbort`/`onError` fires per run), or consume the stream in scope
+before closing:
+
+```typescript
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+const client = await createMCPClient({
+  transport: { type: 'http', url: '...' },
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  tools: await client.tools(),
+  middleware: [
+    {
+      name: 'mcp-close',
+      onFinish: () => client.close(),
+      onAbort: () => client.close(),
+      onError: () => client.close(),
+    },
+  ],
+})
+return toServerSentEventsResponse(stream)
+```
+
+### b. HIGH: importing `stdioTransport` from the main entry point
+
+`stdioTransport` is only available from `@tanstack/ai-mcp/stdio`. Importing it
+from `@tanstack/ai-mcp` will fail with a module-not-found error and would
+bundle Node.js child-process code into edge bundles.
+
+Wrong:
+
+```typescript
+import { stdioTransport } from '@tanstack/ai-mcp' // does not exist here
+```
+
+Correct:
+
+```typescript
+import { stdioTransport } from '@tanstack/ai-mcp/stdio'
+```
+
+### c. MEDIUM: using `client.tools([defs])` without matching names
+
+The name field on each `toolDefinition` must exactly match the tool name the MCP
+server exposes. Mismatches throw `MCPToolNotFoundError` at call time, not at
+type-check time (unless generated types are in use).
+
+### d. MEDIUM: not setting a prefix when multiple servers share tool names
+
+Two different errors can arise depending on where the collision is detected:
+
+- **Within a single `createMCPClients` pool** — calling `pool.tools()` throws
+  `DuplicateToolNameError` (from `@tanstack/ai-mcp`) when two servers in that
+  pool expose the same name with no prefix to separate them.
+- **Across separate `mcp.clients` entries in `chat()`** — `chat()` throws
+  `MCPDuplicateToolNameError` (from `@tanstack/ai`) after merging discovered
+  tools from all `mcp.clients` entries.
+
+In both cases, the fix is the same: use `createMCPClients` (which auto-prefixes
+by config key) or set an explicit `prefix` on each `createMCPClient` call.
+
+## Cross-References
+
+- See also: ai-core/tool-calling/SKILL.md — MCP tools are ServerTools; all tool
+  patterns (approval, lazy, client-side) apply.
+- See also: ai-core/chat-experience/SKILL.md — wiring tools into `chat()`.
diff --git a/packages/ai-mcp/src/cli/bin.ts b/packages/ai-mcp/src/cli/bin.ts
new file mode 100644
index 000000000..e380ce6cc
--- /dev/null
+++ b/packages/ai-mcp/src/cli/bin.ts
@@ -0,0 +1,32 @@
+import { writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { loadConfig } from './config'
+import { introspectServer } from './introspect'
+import { emitDescriptors } from './emit'
+import type { EmitInput } from './emit'
+
+async function generate(cwd = process.cwd()): Promise<void> {
+  const config = await loadConfig(cwd)
+  const input: EmitInput = {}
+  for (const [name, server] of Object.entries(config.servers)) {
+    process.stderr.write(`Introspecting MCP server "${name}"…\n`)
+    const surface = await introspectServer(server)
+    input[name] = { prefix: server.prefix, surface }
+  }
+  const out = await emitDescriptors(input)
+  const outPath = resolve(cwd, config.outFile)
+  writeFileSync(outPath, out, 'utf8')
+  process.stderr.write(`Wrote ${outPath}\n`)
+}
+
+const cmd = process.argv[2]
+if (cmd === 'generate') {
+  generate().catch((err: unknown) => {
+    const msg = err instanceof Error ? (err.stack ?? String(err)) : String(err)
+    process.stderr.write(msg + '\n')
+    process.exit(1)
+  })
+} else {
+  process.stderr.write('Usage: tanstack-ai-mcp generate\n')
+  process.exit(cmd ? 1 : 0)
+}
diff --git a/packages/ai-mcp/src/cli/config.ts b/packages/ai-mcp/src/cli/config.ts
new file mode 100644
index 000000000..7e7a58278
--- /dev/null
+++ b/packages/ai-mcp/src/cli/config.ts
@@ -0,0 +1,23 @@
+import type { MCPCodegenConfig } from './define-config'
+
+export type { CodegenServerConfig, MCPCodegenConfig } from './define-config'
+export { defineConfig } from './define-config'
+
+/** Load mcp.config.ts (via jiti) or mcp.config.json from cwd. */
+export async function loadConfig(cwd: string): Promise<MCPCodegenConfig> {
+  const { existsSync } = await import('node:fs')
+  const { join } = await import('node:path')
+  const tsPath = join(cwd, 'mcp.config.ts')
+  const jsonPath = join(cwd, 'mcp.config.json')
+  if (existsSync(tsPath)) {
+    const { createJiti } = await import('jiti')
+    const jiti = createJiti(import.meta.url)
+    const mod = await jiti.import<{ default: MCPCodegenConfig }>(tsPath)
+    return mod.default
+  }
+  if (existsSync(jsonPath)) {
+    const { readFileSync } = await import('node:fs')
+    return JSON.parse(readFileSync(jsonPath, 'utf8')) as MCPCodegenConfig
+  }
+  throw new Error('No mcp.config.ts or mcp.config.json found in ' + cwd)
+}
diff --git a/packages/ai-mcp/src/cli/define-config.ts b/packages/ai-mcp/src/cli/define-config.ts
new file mode 100644
index 000000000..cd0487e30
--- /dev/null
+++ b/packages/ai-mcp/src/cli/define-config.ts
@@ -0,0 +1,17 @@
+import type { TransportConfig } from '../transport'
+
+export interface CodegenServerConfig {
+  transport: TransportConfig
+  /** Tool-name prefix; must match the runtime `createMCPClient({ prefix })`. */
+  prefix?: string
+}
+
+export interface MCPCodegenConfig {
+  servers: Record<string, CodegenServerConfig>
+  /** Output file for the generated descriptor types. */
+  outFile: string
+}
+
+export function defineConfig(config: MCPCodegenConfig): MCPCodegenConfig {
+  return config
+}
diff --git a/packages/ai-mcp/src/cli/emit.ts b/packages/ai-mcp/src/cli/emit.ts
new file mode 100644
index 000000000..31b26bd86
--- /dev/null
+++ b/packages/ai-mcp/src/cli/emit.ts
@@ -0,0 +1,139 @@
+import { compile } from 'json-schema-to-typescript'
+import type { ServerSurface } from './introspect'
+
+/**
+ * Convert an arbitrary server/tool name into a valid PascalCase identifier.
+ * Falls back to `Generated` for names with no alphanumeric characters and
+ * prefixes an underscore when the result would start with a digit.
+ */
+function pascal(name: string): string {
+  const base = name
+    .replace(/[^a-zA-Z0-9]+/g, ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join('')
+  const safe = base || 'Generated'
+  return /^[A-Za-z_]/.test(safe) ? safe : `_${safe}`
+}
+
+/** Escape a value as a TypeScript string literal (handles quotes/newlines). */
+function tsString(value: string): string {
+  return JSON.stringify(value)
+}
+
+/**
+ * Compile a JSON Schema into a TypeScript type via `json-schema-to-typescript`.
+ * Returns `'unknown'` for absent/non-object schemas. The compiled output is an
+ * `export interface <typeName> { ... }` declaration which callers inline via
+ * {@link inlineBody}.
+ */
+async function schemaToType(
+  schema: unknown,
+  typeName: string,
+): Promise<string> {
+  if (!schema || typeof schema !== 'object') return 'unknown'
+  const compiled = await compile(schema, typeName, {
+    bannerComment: '',
+    additionalProperties: false,
+    declareExternallyReferenced: true,
+  })
+  return compiled.trim()
+}
+
+export interface EmitInput {
+  [serverName: string]: { prefix?: string; surface: ServerSurface }
+}
+
+export async function emitDescriptors(input: EmitInput): Promise<string> {
+  const blocks: Array<string> = [
+    '// AUTO-GENERATED by `npx @tanstack/ai-mcp generate`. Do not edit.',
+    "import type { ServerDescriptor } from '@tanstack/ai-mcp'",
+    '',
+  ]
+  // Track config-key -> interface-name so we can emit the combined pool map.
+  const mapEntries: Array<[string, string]> = []
+  // Distinct server keys can pascal-case to the same identifier
+  // (`foo-bar` vs `foo_bar`) — fail loudly rather than emit duplicate
+  // interface declarations.
+  const seenIfaces = new Set<string>()
+  for (const [serverName, { prefix, surface }] of Object.entries(input)) {
+    const iface = `${pascal(serverName)}Server`
+    if (seenIfaces.has(iface)) {
+      throw new Error(
+        `Interface name collision for server key "${serverName}" -> ${iface}. ` +
+          `Rename one of the colliding servers in your codegen config.`,
+      )
+    }
+    seenIfaces.add(iface)
+    mapEntries.push([serverName, iface])
+    const toolEntries: Array<string> = []
+    for (const tool of surface.tools) {
+      const key = prefix ? `${prefix}_${tool.name}` : tool.name
+      const inputType = await schemaToType(
+        tool.inputSchema,
+        `${pascal(key)}Input`,
+      )
+      const outputType = tool.outputSchema
+        ? await schemaToType(tool.outputSchema, `${pascal(key)}Output`)
+        : 'unknown'
+      // Inline the compiled interface bodies as anonymous object types.
+      toolEntries.push(
+        `    ${tsString(key)}: { input: ${inlineBody(inputType)}; output: ${inlineBody(outputType)} }`,
+      )
+    }
+    blocks.push(
+      `export interface ${iface} extends ServerDescriptor {`,
+      `  tools: {`,
+      toolEntries.join('\n'),
+      `  }`,
+      `  resources: ${emitResources(surface)}`,
+      `  prompts: ${emitPrompts(surface)}`,
+      `  capabilities: ${JSON.stringify(surface.capabilities)} & Record<string, unknown>`,
+      `}`,
+      '',
+    )
+  }
+  // Combined map for createMCPClients<MCPServers>(...). Keys = config keys
+  // verbatim (NOT pascal-cased) so they match the runtime config object and
+  // pool.clients access.
+  blocks.push(
+    'export interface MCPServers extends Record<string, ServerDescriptor> {',
+    ...mapEntries.map(([key, iface]) => `  ${tsString(key)}: ${iface}`),
+    '}',
+    '',
+  )
+  return blocks.join('\n')
+}
+
+/**
+ * Extract the `{ ... }` body from a compiled `export interface X { ... }`
+ * declaration so it can be inlined as an anonymous object type. Collapses
+ * newlines onto a single line. Falls back to `unknown` when no brace is found
+ * (e.g. the compiled type is itself `unknown`).
+ */
+function inlineBody(compiled: string): string {
+  const brace = compiled.indexOf('{')
+  return brace >= 0
+    ? compiled.slice(brace).replace(/\n/g, ' ').trim()
+    : 'unknown'
+}
+
+function emitResources(s: ServerSurface): string {
+  if (!s.resources.length) return '{}'
+  return `{ ${s.resources
+    .map(
+      (r) => `${tsString(r.uri)}: { uri: ${tsString(r.uri)}; data: unknown }`,
+    )
+    .join('; ')} }`
+}
+
+function emitPrompts(s: ServerSurface): string {
+  if (!s.prompts.length) return '{}'
+  return `{ ${s.prompts
+    .map(
+      (p) =>
+        `${tsString(p.name)}: { args: Record<string, string>; messages: unknown }`,
+    )
+    .join('; ')} }`
+}
diff --git a/packages/ai-mcp/src/cli/introspect.ts b/packages/ai-mcp/src/cli/introspect.ts
new file mode 100644
index 000000000..3d844f24e
--- /dev/null
+++ b/packages/ai-mcp/src/cli/introspect.ts
@@ -0,0 +1,90 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { resolveTransport } from '../transport'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import type { CodegenServerConfig } from './define-config'
+
+export interface ServerSurface {
+  tools: Array<{
+    name: string
+    inputSchema: unknown
+    outputSchema?: unknown
+    description?: string
+  }>
+  resources: Array<{ uri: string; name?: string }>
+  prompts: Array<{
+    name: string
+    arguments?: Array<{ name: string; required?: boolean }>
+  }>
+  capabilities: Record<string, unknown>
+}
+
+/** Drain a cursor-paginated MCP list endpoint into a single array. */
+async function listAll<TItem>(
+  fetchPage: (
+    cursor: string | undefined,
+  ) => Promise<{ items: Array<TItem>; nextCursor?: string }>,
+): Promise<Array<TItem>> {
+  const all: Array<TItem> = []
+  let cursor: string | undefined
+  do {
+    const page = await fetchPage(cursor)
+    all.push(...page.items)
+    cursor = page.nextCursor
+  } while (cursor)
+  return all
+}
+
+export async function introspectFromTransport(
+  transport: Transport,
+): Promise<ServerSurface> {
+  const client = new Client({
+    name: 'tanstack-ai-mcp-codegen',
+    version: '0.0.1',
+  })
+  try {
+    await client.connect(transport)
+    const caps = (client.getServerCapabilities() ?? {}) as Record<
+      string,
+      unknown
+    >
+    const tools = caps['tools']
+      ? await listAll(async (cursor) => {
+          const r = await client.listTools({ cursor })
+          return { items: r.tools, nextCursor: r.nextCursor }
+        })
+      : []
+    const resources = caps['resources']
+      ? await listAll(async (cursor) => {
+          const r = await client.listResources({ cursor })
+          return { items: r.resources, nextCursor: r.nextCursor }
+        })
+      : []
+    const prompts = caps['prompts']
+      ? await listAll(async (cursor) => {
+          const r = await client.listPrompts({ cursor })
+          return { items: r.prompts, nextCursor: r.nextCursor }
+        })
+      : []
+    return {
+      tools: tools.map((t) => ({
+        name: t.name,
+        inputSchema: t.inputSchema,
+        outputSchema: (t as { outputSchema?: unknown }).outputSchema,
+        description: t.description,
+      })),
+      resources: resources.map((r) => ({ uri: r.uri, name: r.name })),
+      prompts: prompts.map((p) => ({ name: p.name, arguments: p.arguments })),
+      capabilities: caps,
+    }
+  } finally {
+    // Guarded so a close() failure can't mask the original error.
+    await client.close().catch(() => undefined)
+  }
+}
+
+export async function introspectServer(
+  config: CodegenServerConfig,
+): Promise<ServerSurface> {
+  const transport = await resolveTransport(config.transport)
+  return introspectFromTransport(transport)
+}
diff --git a/packages/ai-mcp/src/client.ts b/packages/ai-mcp/src/client.ts
new file mode 100644
index 000000000..05ce03db5
--- /dev/null
+++ b/packages/ai-mcp/src/client.ts
@@ -0,0 +1,194 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import {
+  DuplicateToolNameError,
+  MCPConnectionError,
+  MCPTaskRequiredToolError,
+  MCPToolNotFoundError,
+} from './errors'
+import { makeMcpExecute, requiresTaskExecution, toServerTools } from './tools'
+import { resolveTransport } from './transport'
+import type {
+  AnyToolDefinition,
+  AutomaticDescriptor,
+  DescriptorTools,
+  MCPClientOptions,
+  MappedServerTools,
+  ServerDescriptor,
+  ToolsOptions,
+} from './types'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import type {
+  GetPromptResult,
+  Prompt,
+  ReadResourceResult,
+  Resource,
+  ResourceTemplate,
+} from '@modelcontextprotocol/sdk/types.js'
+import type { ServerTool } from '@tanstack/ai'
+
+export interface MCPClient<
+  TServer extends ServerDescriptor = AutomaticDescriptor,
+> {
+  readonly capabilities: TServer['capabilities']
+  /**
+   * Auto-discovery: every server tool as a ServerTool. With a generated
+   * descriptor, tool names are typed as the descriptor's name literals;
+   * args/results stay untyped — use the `tools(defs)` overload for typed args.
+   */
+  tools: {
+    (options?: ToolsOptions): Promise<DescriptorTools<TServer>>
+    /**
+     * Explicit: bind these TanStack toolDefinitions to the server (typed +
+     * validated, allowlist). Note: when the client has a `prefix`, the
+     * runtime tool name is `${prefix}_${def.name}` while the static `TName`
+     * stays the unprefixed definition name.
+     */
+    <const TDefs extends ReadonlyArray<AnyToolDefinition>>(
+      defs: TDefs,
+      options?: ToolsOptions,
+    ): Promise<MappedServerTools<TDefs>>
+  }
+  resources: () => Promise<Array<Resource>>
+  readResource: (uri: string) => Promise<ReadResourceResult>
+  resourceTemplates: () => Promise<Array<ResourceTemplate>>
+  prompts: () => Promise<Array<Prompt>>
+  getPrompt: (
+    name: string,
+    args?: Record<string, string>,
+  ) => Promise<GetPromptResult>
+  close: () => Promise<void>
+  [Symbol.asyncDispose]: () => Promise<void>
+}
+
+class MCPClientImpl<
+  TServer extends ServerDescriptor,
+> implements MCPClient<TServer> {
+  capabilities: TServer['capabilities'] = {}
+  readonly #client: Client
+  #closed = false
+  private readonly prefix?: string
+
+  constructor(prefix?: string, name = 'tanstack-ai-mcp', version = '0.0.1') {
+    this.prefix = prefix
+    this.#client = new Client({ name, version })
+  }
+
+  async connect(transport: Transport): Promise<void> {
+    try {
+      await this.#client.connect(transport)
+      this.capabilities = this.#client.getServerCapabilities() ?? {}
+    } catch (err) {
+      throw new MCPConnectionError('Failed to connect to MCP server', err)
+    }
+  }
+
+  async tools(
+    defsOrOptions?: ReadonlyArray<AnyToolDefinition> | ToolsOptions,
+    maybeOptions: ToolsOptions = {},
+  ): Promise<Array<ServerTool>> {
+    if (this.#closed) throw new MCPConnectionError('MCP client is closed')
+
+    const isDefs = Array.isArray(defsOrOptions)
+    const options: ToolsOptions = isDefs
+      ? maybeOptions
+      : // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        ((defsOrOptions as ToolsOptions) ?? {}) // SDK interop: defsOrOptions may be undefined at runtime even though TS types it as ToolsOptions here
+
+    let tools: Array<ServerTool>
+    if (isDefs) {
+      // Explicit path: bind each TanStack toolDefinition to the server by name.
+      const available = new Map(
+        (await this.#client.listTools()).tools.map((t) => [t.name, t]),
+      )
+      tools = (defsOrOptions as ReadonlyArray<AnyToolDefinition>).map((def) => {
+        const serverTool = available.get(def.name)
+        if (!serverTool) throw new MCPToolNotFoundError(def.name)
+        // Explicitly binding a task-required tool is an error (it would fail
+        // on every callTool with -32600) — unlike discovery, which skips them.
+        if (requiresTaskExecution(serverTool))
+          throw new MCPTaskRequiredToolError(def.name)
+        const tool = def.server(
+          makeMcpExecute(this.#client, def.name, Boolean(def.outputSchema)),
+        ) as ServerTool
+        if (this.prefix) tool.name = `${this.prefix}_${def.name}`
+        if (options.lazy) tool.lazy = true
+        return tool
+      })
+    } else {
+      // Auto-discovery path.
+      const defs = (await this.#client.listTools()).tools
+      tools = toServerTools(this.#client, defs, {
+        prefix: this.prefix,
+        lazy: options.lazy,
+      })
+    }
+
+    // Local duplicate guard (within one client's own list — applies to both branches).
+    const seen = new Set<string>()
+    for (const t of tools) {
+      if (seen.has(t.name)) throw new DuplicateToolNameError(t.name)
+      seen.add(t.name)
+    }
+    return tools
+  }
+
+  async resources(): Promise<Array<Resource>> {
+    if (this.#closed) throw new MCPConnectionError('MCP client is closed')
+    return (await this.#client.listResources()).resources
+  }
+
+  async readResource(uri: string): Promise<ReadResourceResult> {
+    if (this.#closed) throw new MCPConnectionError('MCP client is closed')
+    return this.#client.readResource({ uri })
+  }
+
+  async resourceTemplates(): Promise<Array<ResourceTemplate>> {
+    if (this.#closed) throw new MCPConnectionError('MCP client is closed')
+    return (await this.#client.listResourceTemplates()).resourceTemplates
+  }
+
+  async prompts(): Promise<Array<Prompt>> {
+    if (this.#closed) throw new MCPConnectionError('MCP client is closed')
+    return (await this.#client.listPrompts()).prompts
+  }
+
+  async getPrompt(
+    name: string,
+    args?: Record<string, string>,
+  ): Promise<GetPromptResult> {
+    if (this.#closed) throw new MCPConnectionError('MCP client is closed')
+    return this.#client.getPrompt({ name, arguments: args })
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) return
+    this.#closed = true
+    await this.#client.close()
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.close()
+  }
+}
+
+export async function createMCPClient<
+  TServer extends ServerDescriptor = AutomaticDescriptor,
+>(options: MCPClientOptions): Promise<MCPClient<TServer>> {
+  const transport = await resolveTransport(options.transport)
+  const impl = new MCPClientImpl<TServer>(
+    options.prefix,
+    options.name,
+    options.version,
+  )
+  await impl.connect(transport)
+  return impl
+}
+
+/** Test-only: connect directly from a transport instance (skips resolveTransport). */
+export async function createMCPClientFromTransport<
+  TServer extends ServerDescriptor = AutomaticDescriptor,
+>(transport: Transport, prefix?: string): Promise<MCPClient<TServer>> {
+  const impl = new MCPClientImpl<TServer>(prefix)
+  await impl.connect(transport)
+  return impl
+}
diff --git a/packages/ai-mcp/src/errors.ts b/packages/ai-mcp/src/errors.ts
new file mode 100644
index 000000000..467fc4edc
--- /dev/null
+++ b/packages/ai-mcp/src/errors.ts
@@ -0,0 +1,42 @@
+export class MCPConnectionError extends Error {
+  constructor(
+    message: string,
+    public override readonly cause?: unknown,
+  ) {
+    super(message)
+    this.name = 'MCPConnectionError'
+  }
+}
+
+export class DuplicateToolNameError extends Error {
+  constructor(public readonly toolName: string) {
+    super(
+      `Duplicate MCP tool name "${toolName}". Set a unique \`prefix\` on one of the ` +
+        `MCP clients (createMCPClient({ transport, prefix: '...' })) to disambiguate.`,
+    )
+    this.name = 'DuplicateToolNameError'
+  }
+}
+
+export class MCPTaskRequiredToolError extends Error {
+  constructor(public readonly toolName: string) {
+    super(
+      `MCP tool "${toolName}" declares \`execution.taskSupport: 'required'\` — it can ` +
+        `only be invoked via the MCP SDK's experimental task-based execution ` +
+        `(client.experimental.tasks.callToolStream()), which @tanstack/ai-mcp does not ` +
+        `support yet. Task-required tools are excluded from tools() auto-discovery; ` +
+        `binding one explicitly via tools([toolDefinition(...)]) is an error.`,
+    )
+    this.name = 'MCPTaskRequiredToolError'
+  }
+}
+
+export class MCPToolNotFoundError extends Error {
+  constructor(public readonly toolName: string) {
+    super(
+      `toolDefinition name "${toolName}" was passed to mcp.tools([...]) but the MCP ` +
+        `server exposes no tool with that name. Check the name or run mcp.tools() to list.`,
+    )
+    this.name = 'MCPToolNotFoundError'
+  }
+}
diff --git a/packages/ai-mcp/src/index.ts b/packages/ai-mcp/src/index.ts
new file mode 100644
index 000000000..d16ff0bd6
--- /dev/null
+++ b/packages/ai-mcp/src/index.ts
@@ -0,0 +1,31 @@
+export { createMCPClient, createMCPClientFromTransport } from './client'
+export type { MCPClient } from './client'
+export type {
+  AnyToolDefinition,
+  MappedServerTools,
+  MCPClientOptions,
+  ServerDescriptor,
+  ToolsOptions,
+} from './types'
+export type {
+  TransportConfig,
+  TransportInput,
+  HttpTransportConfig,
+  SseTransportConfig,
+  StdioTransportConfig,
+} from './transport'
+export type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+export { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
+export {
+  MCPConnectionError,
+  DuplicateToolNameError,
+  MCPTaskRequiredToolError,
+  MCPToolNotFoundError,
+} from './errors'
+// Converters added in Phase 4:
+export { mcpResourceToContentPart } from './resources'
+export { mcpPromptToMessages } from './prompts'
+export { createMCPClients } from './pool'
+export type { MCPClients, MCPClientsConfig } from './pool'
+export { defineConfig } from './cli/define-config'
+export type { MCPCodegenConfig, CodegenServerConfig } from './cli/define-config'
diff --git a/packages/ai-mcp/src/pool.ts b/packages/ai-mcp/src/pool.ts
new file mode 100644
index 000000000..cd6d5f1ba
--- /dev/null
+++ b/packages/ai-mcp/src/pool.ts
@@ -0,0 +1,127 @@
+import { createMCPClient } from './client'
+import { DuplicateToolNameError, MCPConnectionError } from './errors'
+import type { MCPClient } from './client'
+import type { MCPClientOptions, ServerDescriptor, ToolsOptions } from './types'
+import type { ServerTool } from '@tanstack/ai'
+
+export type MCPClientsConfig = Record<string, MCPClientOptions>
+
+export interface MCPClients<
+  TServers extends Record<string, ServerDescriptor> = Record<
+    string,
+    ServerDescriptor
+  >,
+> {
+  /** Typed per-server access (typed defs, resources, prompts on one server). */
+  readonly clients: { [K in keyof TServers]: MCPClient<TServers[K]> }
+  /**
+   * All servers' tools, flattened and auto-prefixed by config key.
+   * `options` (including `lazy`) is forwarded to every client's `tools()`.
+   */
+  tools: (options?: ToolsOptions) => Promise<Array<ServerTool>>
+  /** Close every client. */
+  close: () => Promise<void>
+  [Symbol.asyncDispose]: () => Promise<void>
+}
+
+export async function createMCPClients<
+  TServers extends Record<string, ServerDescriptor> = Record<
+    string,
+    ServerDescriptor
+  >,
+>(
+  // When TServers is a generated `MCPServers` map, the config keys are
+  // constrained to the declared servers (missing/typo'd key → compile error).
+  config: { [K in keyof TServers]: MCPClientOptions } & MCPClientsConfig,
+): Promise<MCPClients<TServers>> {
+  const names = Object.keys(config)
+
+  // Connect all in parallel; on any failure, close the successes and throw once.
+  const settled = await Promise.allSettled(
+    names.map(async (name) => {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const opts = config[name]!
+      // default prefix = config key; `prefix: ''` disables; explicit string wins
+      const prefix = opts.prefix === undefined ? name : opts.prefix || undefined
+      const client = await createMCPClient({ ...opts, prefix })
+      return [name, client] as const
+    }),
+  )
+
+  const ok = settled.filter(
+    (
+      r,
+    ): r is PromiseFulfilledResult<
+      readonly [string, MCPClient<ServerDescriptor>]
+    > => r.status === 'fulfilled',
+  )
+  const failed = settled
+    .map((r, i) => (r.status === 'rejected' ? names[i] : null))
+    .filter((n): n is string => n !== null)
+
+  if (failed.length > 0) {
+    // Cleanup already-connected clients — no leaks.
+    await Promise.allSettled(ok.map((r) => r.value[1].close()))
+    throw new MCPConnectionError(
+      `Failed to connect MCP server(s): ${failed.join(', ')}`,
+    )
+  }
+
+  // Cast via `unknown`: the runtime map is descriptor-agnostic
+  // (`MCPClient<ServerDescriptor>` values), but per-key the public type is the
+  // narrowed `MCPClient<TServers[K]>`. Those no longer structurally overlap
+  // because `tools()` is now descriptor-typed (`DescriptorTools<TServer>`), yet
+  // the generated descriptor is a compile-time overlay only — the runtime
+  // values are identical, so the through-`unknown` cast is sound here.
+  // eslint-disable-next-line no-restricted-syntax -- descriptor is a compile-time overlay; runtime MCPClient values are identical regardless of TServer
+  const clients = Object.fromEntries(ok.map((r) => r.value)) as unknown as {
+    [K in keyof TServers]: MCPClient<TServers[K]>
+  }
+
+  const pool: MCPClients<TServers> = {
+    clients,
+    async tools(options?: ToolsOptions): Promise<Array<ServerTool>> {
+      // Settle (like the connect path) so a single failing server is reported
+      // by config key instead of rejecting with an unattributed SDK error.
+      const entries = Object.entries(clients)
+      const results = await Promise.allSettled(
+        entries.map(([, c]) =>
+          (c as MCPClient<ServerDescriptor>).tools(options),
+        ),
+      )
+      const failedNames = entries
+        .map(([key], i) => (results[i]?.status === 'rejected' ? key : null))
+        .filter((k): k is string => k !== null)
+      if (failedNames.length > 0) {
+        const firstFailure = results.find(
+          (r): r is PromiseRejectedResult => r.status === 'rejected',
+        )
+        throw new MCPConnectionError(
+          `Failed to list tools from MCP server(s): ${failedNames.join(', ')}`,
+          firstFailure?.reason,
+        )
+      }
+      const all = results.flatMap((r) =>
+        r.status === 'fulfilled' ? r.value : [],
+      )
+      const seen = new Set<string>()
+      for (const t of all) {
+        if (seen.has(t.name)) throw new DuplicateToolNameError(t.name)
+        seen.add(t.name)
+      }
+      return all
+    },
+    async close(): Promise<void> {
+      await Promise.all(
+        Object.values(clients).map((c) =>
+          (c as MCPClient<ServerDescriptor>).close(),
+        ),
+      )
+    },
+    async [Symbol.asyncDispose](): Promise<void> {
+      await pool.close()
+    },
+  }
+
+  return pool
+}
diff --git a/packages/ai-mcp/src/prompts.ts b/packages/ai-mcp/src/prompts.ts
new file mode 100644
index 000000000..670a0e77e
--- /dev/null
+++ b/packages/ai-mcp/src/prompts.ts
@@ -0,0 +1,28 @@
+import type { ModelMessage } from '@tanstack/ai'
+
+/**
+ * Convert an MCP GetPromptResult into an array of ModelMessages suitable for
+ * passing to `chat()` or any TanStack AI adapter.
+ *
+ * @param prompt - An object with a `messages` array as returned by the MCP
+ *   `prompts/get` endpoint.
+ * @returns An array of {@link ModelMessage} values.
+ */
+export function mcpPromptToMessages(prompt: {
+  messages: Array<{
+    role: string
+    content?: { type: string; text?: string } | null
+  }>
+}): Array<ModelMessage> {
+  return prompt.messages.map((m) => {
+    const role: 'user' | 'assistant' =
+      m.role === 'assistant' ? 'assistant' : 'user'
+    const content =
+      m.content?.type === 'text' && m.content.text !== undefined
+        ? m.content.text
+        : // `?? null` so absent content stringifies to 'null' rather than
+          // producing `undefined` (invalid for ModelMessage['content']).
+          JSON.stringify(m.content ?? null)
+    return { role, content }
+  })
+}
diff --git a/packages/ai-mcp/src/resources.ts b/packages/ai-mcp/src/resources.ts
new file mode 100644
index 000000000..10835301e
--- /dev/null
+++ b/packages/ai-mcp/src/resources.ts
@@ -0,0 +1,23 @@
+import type { ContentPart } from '@tanstack/ai'
+
+/**
+ * Converts a single MCP resource content block to a TanStack `ContentPart`.
+ *
+ * - `text` field present → `{ type: 'text', content: text }`
+ * - `blob` field present → `{ type: 'text', content: '[binary resource <uri>]' }`
+ * - otherwise          → `{ type: 'text', content: JSON.stringify(content) }`
+ */
+export function mcpResourceToContentPart(content: {
+  uri?: string
+  text?: string
+  blob?: string
+  [key: string]: unknown
+}): ContentPart {
+  if (typeof content.text === 'string') {
+    return { type: 'text', content: content.text }
+  }
+  if (typeof content.blob === 'string') {
+    return { type: 'text', content: `[binary resource ${content.uri ?? ''}]` }
+  }
+  return { type: 'text', content: JSON.stringify(content) }
+}
diff --git a/packages/ai-mcp/src/stdio.ts b/packages/ai-mcp/src/stdio.ts
new file mode 100644
index 000000000..e2dbda0c1
--- /dev/null
+++ b/packages/ai-mcp/src/stdio.ts
@@ -0,0 +1,15 @@
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import type { StdioTransportConfig } from './transport'
+
+/** Build a stdio transport instance to pass as `createMCPClient({ transport })`. Node-only. */
+export function stdioTransport(
+  config: Omit<StdioTransportConfig, 'type'>,
+): Transport {
+  return new StdioClientTransport({
+    command: config.command,
+    args: config.args,
+    env: config.env,
+    cwd: config.cwd,
+  })
+}
diff --git a/packages/ai-mcp/src/tools.ts b/packages/ai-mcp/src/tools.ts
new file mode 100644
index 000000000..6cb9480ce
--- /dev/null
+++ b/packages/ai-mcp/src/tools.ts
@@ -0,0 +1,111 @@
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import type { Tool as McpToolDef } from '@modelcontextprotocol/sdk/types.js'
+import type { ContentPart, ServerTool } from '@tanstack/ai'
+
+interface ConvertOptions {
+  prefix?: string
+  lazy?: boolean
+}
+
+export function mcpContentToTanstack(
+  content: Array<any>,
+): string | Array<ContentPart> {
+  // Single text block → plain string (most common, best for the model).
+  if (content.length === 1 && content[0]?.type === 'text')
+    return content[0].text
+  return content.map((c): ContentPart => {
+    switch (c.type) {
+      case 'text':
+        return { type: 'text', content: c.text }
+      case 'image':
+        return {
+          type: 'image',
+          source: { type: 'data', value: c.data, mimeType: c.mimeType },
+        }
+      case 'resource':
+        return { type: 'text', content: JSON.stringify(c.resource) }
+      default:
+        return { type: 'text', content: JSON.stringify(c) }
+    }
+  })
+}
+
+/**
+ * Build the execute body that proxies a TanStack tool call to an MCP server's
+ * `callTool`. Shared by auto-discovery and the definition path.
+ *
+ * @param preferStructured when true (i.e. the tool declares an outputSchema),
+ *   return `result.structuredContent` if present so the existing output
+ *   validation in `executeServerTool` validates MCP's typed payload rather than
+ *   a JSON-in-text blob. Otherwise normalize `content[]` → string | ContentPart[].
+ */
+export function makeMcpExecute(
+  client: Client,
+  mcpName: string,
+  preferStructured: boolean,
+) {
+  return async (args: unknown, ctx?: { abortSignal?: AbortSignal }) => {
+    ctx?.abortSignal?.throwIfAborted()
+    const result = await client.callTool(
+      { name: mcpName, arguments: (args ?? {}) as Record<string, unknown> },
+      undefined,
+      { signal: ctx?.abortSignal },
+    )
+    if (result.isError) {
+      const text = Array.isArray(result.content)
+        ? mcpContentToTanstack(result.content)
+        : undefined
+      const detail = typeof text === 'string' ? text : JSON.stringify(text)
+      throw new Error(
+        text === undefined
+          ? `MCP tool "${mcpName}" returned an error`
+          : `MCP tool "${mcpName}" returned an error: ${detail}`,
+      )
+    }
+    if (preferStructured && result.structuredContent !== undefined) {
+      return result.structuredContent
+    }
+    return mcpContentToTanstack(result.content as Array<any>)
+  }
+}
+
+/**
+ * A tool with `execution.taskSupport: 'required'` can only run through the
+ * SDK's experimental task-based execution (`tasks/callToolStream`) — plain
+ * `callTool` is rejected by the server with -32600. Until task execution is
+ * supported, such tools must not be offered to the model.
+ */
+export function requiresTaskExecution(def: McpToolDef): boolean {
+  return def.execution?.taskSupport === 'required'
+}
+
+/**
+ * Auto-discovery path: turn raw MCP tool defs into ServerTools (args typed
+ * `unknown`). Task-required tools are excluded — they cannot be invoked via
+ * plain `callTool` (see {@link requiresTaskExecution}).
+ */
+export function toServerTools(
+  client: Client,
+  defs: Array<McpToolDef>,
+  options: ConvertOptions,
+): Array<ServerTool> {
+  return defs
+    .filter((def) => !requiresTaskExecution(def))
+    .map((def) => {
+      const name = options.prefix ? `${options.prefix}_${def.name}` : def.name
+      const tool: ServerTool = {
+        __toolSide: 'server',
+        name,
+        description: def.description ?? '',
+        inputSchema: (def.inputSchema as any) ?? {
+          type: 'object',
+          properties: {},
+        },
+        ...(def.outputSchema ? { outputSchema: def.outputSchema as any } : {}),
+        ...(options.lazy ? { lazy: true } : {}),
+        metadata: { mcp: { serverToolName: def.name } },
+        execute: makeMcpExecute(client, def.name, Boolean(def.outputSchema)),
+      }
+      return tool
+    })
+}
diff --git a/packages/ai-mcp/src/transport.ts b/packages/ai-mcp/src/transport.ts
new file mode 100644
index 000000000..9a78ca58c
--- /dev/null
+++ b/packages/ai-mcp/src/transport.ts
@@ -0,0 +1,69 @@
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js'
+
+export interface HttpTransportConfig {
+  type: 'http'
+  url: string
+  headers?: Record<string, string>
+  fetch?: typeof fetch
+  authProvider?: OAuthClientProvider
+}
+
+export interface SseTransportConfig {
+  type: 'sse'
+  url: string
+  headers?: Record<string, string>
+  fetch?: typeof fetch
+  authProvider?: OAuthClientProvider
+}
+
+/** stdio is declared here for typing but constructed only via `@tanstack/ai-mcp/stdio`. */
+export interface StdioTransportConfig {
+  type: 'stdio'
+  command: string
+  args?: Array<string>
+  env?: Record<string, string>
+  cwd?: string
+}
+
+export type TransportConfig =
+  | HttpTransportConfig
+  | SseTransportConfig
+  | StdioTransportConfig
+
+/** Either a built-in config or a ready-made SDK Transport instance (escape hatch). */
+export type TransportInput = TransportConfig | Transport
+
+function isTransportInstance(input: TransportInput): input is Transport {
+  return typeof (input as Transport).start === 'function'
+}
+
+export async function resolveTransport(
+  input: TransportInput,
+): Promise<Transport> {
+  if (isTransportInstance(input)) return input
+
+  switch (input.type) {
+    case 'http':
+      return new StreamableHTTPClientTransport(new URL(input.url), {
+        requestInit: { headers: input.headers },
+        fetch: input.fetch,
+        authProvider: input.authProvider,
+      })
+    case 'sse':
+      return new SSEClientTransport(new URL(input.url), {
+        requestInit: { headers: input.headers },
+        fetch: input.fetch,
+        authProvider: input.authProvider,
+      })
+    case 'stdio':
+      throw new Error(
+        "stdio transport must be created via '@tanstack/ai-mcp/stdio': " +
+          "import { stdioTransport } from '@tanstack/ai-mcp/stdio' and pass the result as `transport`.",
+      )
+    default:
+      throw new Error(`Unknown MCP transport config: ${JSON.stringify(input)}`)
+  }
+}
diff --git a/packages/ai-mcp/src/types.ts b/packages/ai-mcp/src/types.ts
new file mode 100644
index 000000000..b0025bb8e
--- /dev/null
+++ b/packages/ai-mcp/src/types.ts
@@ -0,0 +1,69 @@
+import type { ServerTool, ToolDefinition } from '@tanstack/ai'
+import type { TransportInput } from './transport'
+
+/** A bare tool definition (from `toolDefinition({...})`, no `.server()`/`.client()` called). */
+export type AnyToolDefinition = ToolDefinition<any, any, string>
+
+/** Compile-time-only descriptor of an MCP server, emitted by the codegen CLI. */
+export interface ServerDescriptor {
+  tools: Record<string, { input: unknown; output: unknown }>
+  resources: Record<string, { uri: string; data: unknown }>
+  prompts: Record<string, { args: unknown; messages: unknown }>
+  capabilities: Record<string, unknown>
+}
+
+/** The "no generated types" default — discovery yields untyped tools. */
+export type AutomaticDescriptor = ServerDescriptor
+
+export interface MCPClientOptions {
+  transport: TransportInput
+  /** Tool-name prefix (e.g. 'github' → 'github_search'). Default: none. */
+  prefix?: string
+  /** Client identity sent to the server. */
+  name?: string
+  version?: string
+}
+
+export interface ToolsOptions {
+  /** Mark tools `lazy: true` to defer schema-sending via LazyToolManager. */
+  lazy?: boolean
+}
+
+/**
+ * Per-element ServerTool type from a tool definition. `def.server(execute)`
+ * already returns a fully-typed `ServerTool<TInput, TOutput, TName>`, so a
+ * mapped tuple over the passed definitions preserves per-tool types.
+ */
+export type ServerToolFromDef<TDef> =
+  TDef extends ToolDefinition<infer TInput, infer TOutput, infer TName>
+    ? ServerTool<TInput, TOutput, TName>
+    : never
+
+export type MappedServerTools<TDefs extends ReadonlyArray<AnyToolDefinition>> =
+  {
+    -readonly [K in keyof TDefs]: ServerToolFromDef<TDefs[K]>
+  }
+
+/**
+ * ServerTool named by one descriptor tool key `TKey`.
+ *
+ * Only the tool **name** survives into the discovery result — input/output
+ * stay `any` because `ServerTool`'s generics are *schema* types
+ * (`extends SchemaInput`), while the descriptor carries plain *value* types
+ * emitted by the codegen CLI. Per-tool argument/result typing comes from the
+ * explicit `tools(defs)` overload via `MappedServerTools`.
+ */
+type DescribedTool<TKey extends string> = ServerTool<any, any, TKey>
+
+/**
+ * Discovery result typed from the generated descriptor: an array whose
+ * elements' `name` is the union of the descriptor's tool-name literals.
+ * Arguments/results are untyped (`any`) on this path — use the `tools(defs)`
+ * overload for typed args. When TServer is the AutomaticDescriptor (no
+ * generated types), this collapses to `Array<ServerTool>`.
+ */
+export type DescriptorTools<TServer extends ServerDescriptor> = Array<
+  {
+    [K in keyof TServer['tools'] & string]: DescribedTool<K>
+  }[keyof TServer['tools'] & string]
+>
diff --git a/packages/ai-mcp/tests/cli-config.test.ts b/packages/ai-mcp/tests/cli-config.test.ts
new file mode 100644
index 000000000..77eb28b46
--- /dev/null
+++ b/packages/ai-mcp/tests/cli-config.test.ts
@@ -0,0 +1,63 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { defineConfig } from '../src/cli/define-config'
+import { loadConfig } from '../src/cli/config'
+
+describe('defineConfig', () => {
+  it('returns the config verbatim (identity helper for typing)', () => {
+    const cfg = defineConfig({
+      servers: {
+        weather: { transport: { type: 'http', url: 'https://x/mcp' } },
+      },
+      outFile: './mcp-types.generated.ts',
+    })
+    expect(cfg.servers.weather?.transport.type).toBe('http')
+  })
+})
+
+describe('loadConfig', () => {
+  let tmpDir: string | undefined
+
+  afterEach(() => {
+    if (tmpDir) {
+      rmSync(tmpDir, { recursive: true, force: true })
+      tmpDir = undefined
+    }
+  })
+
+  it('JSON fallback: reads and parses mcp.config.json when no .ts file exists', async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'mcp-cfg-'))
+    const configContent = {
+      servers: {
+        weather: {
+          transport: { type: 'http', url: 'https://x/mcp' },
+        },
+      },
+      outFile: './mcp-types.generated.ts',
+    }
+    writeFileSync(
+      join(tmpDir, 'mcp.config.json'),
+      JSON.stringify(configContent),
+    )
+
+    const cfg = await loadConfig(tmpDir)
+
+    const transport = cfg.servers['weather']?.transport
+    expect(transport?.type).toBe('http')
+    if (transport?.type === 'http' || transport?.type === 'sse') {
+      expect(transport.url).toBe('https://x/mcp')
+    }
+    expect(cfg.outFile).toBe('./mcp-types.generated.ts')
+  })
+
+  it('throw on missing: rejects with the real error message when no config file exists', async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'mcp-cfg-empty-'))
+
+    await expect(loadConfig(tmpDir)).rejects.toThrow(
+      /No mcp\.config\.ts or mcp\.config\.json found in /,
+    )
+    await expect(loadConfig(tmpDir)).rejects.toThrow(tmpDir)
+  })
+})
diff --git a/packages/ai-mcp/tests/cli-emit.test.ts b/packages/ai-mcp/tests/cli-emit.test.ts
new file mode 100644
index 000000000..6e1186db2
--- /dev/null
+++ b/packages/ai-mcp/tests/cli-emit.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+import { emitDescriptors } from '../src/cli/emit'
+
+describe('emitDescriptors', () => {
+  it('emits a ServerDescriptor type per server with typed tool inputs', async () => {
+    const out = await emitDescriptors({
+      weather: {
+        prefix: undefined,
+        surface: {
+          tools: [
+            {
+              name: 'get_weather',
+              inputSchema: {
+                type: 'object',
+                properties: { city: { type: 'string' } },
+                required: ['city'],
+              },
+            },
+          ],
+          resources: [],
+          prompts: [],
+          capabilities: { tools: {} },
+        },
+      },
+    })
+    expect(out).toContain('export interface WeatherServer')
+    expect(out).toContain('get_weather')
+    expect(out).toContain('city')
+    // Combined pool map, keyed by config key, referencing the per-server interface.
+    expect(out).toContain('export interface MCPServers')
+    expect(out).toMatch(/"weather":\s*WeatherServer/)
+  })
+
+  it('escapes hostile names and rejects pascal-case interface collisions', async () => {
+    const surface = {
+      tools: [
+        {
+          name: `quote'"\nbreak`,
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ],
+      resources: [],
+      prompts: [],
+      capabilities: { tools: {} },
+    }
+    // Tool names with quotes/newlines must be escaped in the emitted TS.
+    const out = await emitDescriptors({
+      '1pm-server': { prefix: undefined, surface },
+    })
+    expect(out).toContain(JSON.stringify(`quote'"\nbreak`))
+    // Leading digit gets an underscore prefix to stay a valid identifier.
+    expect(out).toContain('export interface _1pmServerServer')
+
+    // `foo-bar` and `foo_bar` pascal-case identically — must throw, not emit
+    // duplicate interfaces.
+    await expect(
+      emitDescriptors({
+        'foo-bar': { prefix: undefined, surface },
+        foo_bar: { prefix: undefined, surface },
+      }),
+    ).rejects.toThrow(/collision/)
+  })
+})
diff --git a/packages/ai-mcp/tests/cli-introspect.test.ts b/packages/ai-mcp/tests/cli-introspect.test.ts
new file mode 100644
index 000000000..edd43940f
--- /dev/null
+++ b/packages/ai-mcp/tests/cli-introspect.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { introspectFromTransport } from '../src/cli/introspect'
+import { makeFullServer } from './helpers/in-memory-server'
+
+describe('introspect', () => {
+  it('reads the full server surface', async () => {
+    const { clientTransport } = await makeFullServer()
+    const surface = await introspectFromTransport(clientTransport)
+    expect(surface.tools.length).toBeGreaterThan(0)
+    expect(surface.capabilities).toBeDefined()
+    expect(surface.resources.length).toBeGreaterThan(0)
+    expect(surface.prompts.length).toBeGreaterThan(0)
+  })
+})
diff --git a/packages/ai-mcp/tests/client.test.ts b/packages/ai-mcp/tests/client.test.ts
new file mode 100644
index 000000000..95d888654
--- /dev/null
+++ b/packages/ai-mcp/tests/client.test.ts
@@ -0,0 +1,150 @@
+// packages/ai-mcp/tests/client.test.ts
+import { describe, expect, it } from 'vitest'
+import { createMCPClientFromTransport } from '../src/client'
+import {
+  DuplicateToolNameError,
+  MCPConnectionError,
+  MCPTaskRequiredToolError,
+} from '../src/errors'
+import {
+  makeServerWithTaskRequiredTool,
+  makeServerWithWeatherTool,
+} from './helpers/in-memory-server'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+
+describe('createMCPClient', () => {
+  it('connects and returns discovered tools', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    await using client = await createMCPClientFromTransport(clientTransport)
+    const tools = await client.tools()
+    expect(tools.map((t) => t.name)).toContain('get_weather')
+    expect(client.capabilities).toBeDefined()
+  })
+
+  it('binds passed toolDefinitions to the server, typed + validated', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    await using client = await createMCPClientFromTransport(clientTransport)
+    const { toolDefinition } = await import('@tanstack/ai')
+    const { z } = await import('zod')
+    const getWeather = toolDefinition({
+      name: 'get_weather',
+      description: 'Get weather for a city',
+      inputSchema: z.object({ city: z.string() }),
+    })
+    const tools = await client.tools([getWeather])
+    expect(tools).toHaveLength(1)
+    expect(tools[0].name).toBe('get_weather')
+    const result = await tools[0].execute!(
+      { city: 'Brooklyn' },
+      {
+        toolCallId: 't',
+        emitCustomEvent: () => {},
+      },
+    )
+    expect(JSON.stringify(result)).toContain('Sunny in Brooklyn')
+  })
+
+  it('throws MCPToolNotFoundError for a definition the server lacks', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    await using client = await createMCPClientFromTransport(clientTransport)
+    const { toolDefinition } = await import('@tanstack/ai')
+    const { z } = await import('zod')
+    const ghost = toolDefinition({
+      name: 'does_not_exist',
+      description: 'A tool that does not exist on the server',
+      inputSchema: z.object({}),
+    })
+    await expect(client.tools([ghost])).rejects.toThrow(/does_not_exist/)
+  })
+
+  it('throws DuplicateToolNameError when bound defs collide within one tools() call', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    await using client = await createMCPClientFromTransport(clientTransport)
+    const { toolDefinition } = await import('@tanstack/ai')
+    const { z } = await import('zod')
+    const getWeather = toolDefinition({
+      name: 'get_weather',
+      description: 'Get weather for a city',
+      inputSchema: z.object({ city: z.string() }),
+    })
+    // Two defs resolving to the same final tool name trip the client's own
+    // duplicate guard (single tools() call).
+    await expect(client.tools([getWeather, getWeather])).rejects.toThrow(
+      DuplicateToolNameError,
+    )
+  })
+
+  it('applies the client prefix to bound definitions', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    await using client = await createMCPClientFromTransport(
+      clientTransport,
+      'wx',
+    )
+    const { toolDefinition } = await import('@tanstack/ai')
+    const { z } = await import('zod')
+    const getWeather = toolDefinition({
+      name: 'get_weather',
+      description: 'Get weather for a city',
+      inputSchema: z.object({ city: z.string() }),
+    })
+    const tools = await client.tools([getWeather])
+    expect(tools[0].name).toBe('wx_get_weather')
+  })
+
+  it('excludes task-required tools from auto-discovery', async () => {
+    const { clientTransport } = await makeServerWithTaskRequiredTool()
+    await using client = await createMCPClientFromTransport(clientTransport)
+    const names = (await client.tools()).map((t) => t.name)
+    expect(names).toContain('get_weather')
+    expect(names).not.toContain('research_task')
+  })
+
+  it('throws MCPTaskRequiredToolError when binding a task-required tool', async () => {
+    const { clientTransport } = await makeServerWithTaskRequiredTool()
+    await using client = await createMCPClientFromTransport(clientTransport)
+    const { toolDefinition } = await import('@tanstack/ai')
+    const { z } = await import('zod')
+    const researchTask = toolDefinition({
+      name: 'research_task',
+      description: 'A long-running tool that requires task-based execution',
+      inputSchema: z.object({ query: z.string() }),
+    })
+    await expect(client.tools([researchTask])).rejects.toThrow(
+      MCPTaskRequiredToolError,
+    )
+  })
+
+  it('wraps connection failures in MCPConnectionError preserving the cause', async () => {
+    const broken: Transport = {
+      start: async () => {
+        throw new Error('nope')
+      },
+      send: async () => {},
+      close: async () => {},
+    }
+    const err: unknown = await createMCPClientFromTransport(broken).catch(
+      (e: unknown) => e,
+    )
+    expect(err).toBeInstanceOf(MCPConnectionError)
+    expect((err as MCPConnectionError).cause).toBeInstanceOf(Error)
+  })
+
+  it('close() is idempotent', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    const client = await createMCPClientFromTransport(clientTransport)
+    await client.close()
+    await expect(client.close()).resolves.toBeUndefined()
+  })
+
+  it('closes on asyncDispose', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    let client: Awaited<ReturnType<typeof createMCPClientFromTransport>>
+    {
+      await using c = await createMCPClientFromTransport(clientTransport)
+      client = c
+      expect(await c.tools()).toBeDefined()
+    }
+    // after scope exit the client is closed; calling tools() rejects
+    await expect(client.tools()).rejects.toThrow()
+  })
+})
diff --git a/packages/ai-mcp/tests/helpers/in-memory-server.ts b/packages/ai-mcp/tests/helpers/in-memory-server.ts
new file mode 100644
index 000000000..973ac0db0
--- /dev/null
+++ b/packages/ai-mcp/tests/helpers/in-memory-server.ts
@@ -0,0 +1,162 @@
+// packages/ai-mcp/tests/helpers/in-memory-server.ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
+import { z } from 'zod'
+
+/** Build a connected (server, clientTransport) pair over in-memory transports. */
+export async function makeServerWithWeatherTool() {
+  const server = new McpServer({ name: 'weather', version: '1.0.0' })
+  server.registerTool(
+    'get_weather',
+    {
+      description: 'Get weather for a city',
+      inputSchema: { city: z.string() },
+    },
+    async ({ city }) => ({
+      content: [{ type: 'text' as const, text: `Sunny in ${city}` }],
+    }),
+  )
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair()
+  await server.connect(serverTransport)
+  return { server, clientTransport }
+}
+
+/** Build a connected (server, clientTransport) pair whose only tool always returns an MCP error result. */
+export async function makeServerWithFailingTool() {
+  const server = new McpServer({ name: 'failing', version: '1.0.0' })
+  server.registerTool(
+    'always_fails',
+    {
+      description: 'A tool that always returns an error result',
+      inputSchema: {},
+    },
+    async () => ({
+      isError: true,
+      content: [{ type: 'text' as const, text: 'boom' }],
+    }),
+  )
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair()
+  await server.connect(serverTransport)
+  return { server, clientTransport }
+}
+
+/** Build a connected (server, clientTransport) pair with one normal tool and one task-required tool. */
+export async function makeServerWithTaskRequiredTool() {
+  const server = new McpServer({ name: 'tasky', version: '1.0.0' })
+  server.registerTool(
+    'get_weather',
+    {
+      description: 'Get weather for a city',
+      inputSchema: { city: z.string() },
+    },
+    async ({ city }) => ({
+      content: [{ type: 'text' as const, text: `Sunny in ${city}` }],
+    }),
+  )
+  const registered = server.registerTool(
+    'research_task',
+    {
+      description: 'A long-running tool that requires task-based execution',
+      inputSchema: { query: z.string() },
+    },
+    async () => ({
+      content: [{ type: 'text' as const, text: 'unreachable via callTool' }],
+    }),
+  )
+  // registerTool's config doesn't accept `execution` directly in SDK 1.29;
+  // RegisteredTool exposes it as a mutable property consumed at list time.
+  registered.execution = { taskSupport: 'required' }
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair()
+  await server.connect(serverTransport)
+  return { server, clientTransport }
+}
+
+/** Build a connected (server, clientTransport) pair that exposes a static text resource. */
+export async function makeServerWithResource() {
+  const server = new McpServer({ name: 'resource-server', version: '1.0.0' })
+  server.registerResource(
+    'hello',
+    'file:///hello.txt',
+    { description: 'A simple text resource', mimeType: 'text/plain' },
+    async (_uri) => ({
+      contents: [{ uri: 'file:///hello.txt', text: 'hello from resource' }],
+    }),
+  )
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair()
+  await server.connect(serverTransport)
+  return { server, clientTransport }
+}
+
+/** Build a connected (server, clientTransport) pair that exposes a prompt accepting a `code` argument. */
+export async function makeServerWithPrompt() {
+  const server = new McpServer({ name: 'prompt-server', version: '1.0.0' })
+  server.registerPrompt(
+    'review-code',
+    {
+      description: 'Review a code snippet',
+      argsSchema: { code: z.string() },
+    },
+    ({ code }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: { type: 'text' as const, text: `Please review: ${code}` },
+        },
+      ],
+    }),
+  )
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair()
+  await server.connect(serverTransport)
+  return { server, clientTransport }
+}
+
+/** Build a connected (server, clientTransport) pair that exposes one tool, one resource, and one prompt. */
+export async function makeFullServer() {
+  const server = new McpServer({ name: 'full-server', version: '1.0.0' })
+
+  server.registerTool(
+    'get_weather',
+    {
+      description: 'Get weather for a city',
+      inputSchema: { city: z.string() },
+    },
+    async ({ city }) => ({
+      content: [{ type: 'text' as const, text: `Sunny in ${city}` }],
+    }),
+  )
+
+  server.registerResource(
+    'hello',
+    'file:///hello.txt',
+    { description: 'A simple text resource', mimeType: 'text/plain' },
+    async (_uri) => ({
+      contents: [{ uri: 'file:///hello.txt', text: 'hello from resource' }],
+    }),
+  )
+
+  server.registerPrompt(
+    'review-code',
+    {
+      description: 'Review a code snippet',
+      argsSchema: { code: z.string() },
+    },
+    ({ code }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: { type: 'text' as const, text: `Please review: ${code}` },
+        },
+      ],
+    }),
+  )
+
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair()
+  await server.connect(serverTransport)
+  return { server, clientTransport }
+}
diff --git a/packages/ai-mcp/tests/mcp-tool-source.test-d.ts b/packages/ai-mcp/tests/mcp-tool-source.test-d.ts
new file mode 100644
index 000000000..09a5a8ddb
--- /dev/null
+++ b/packages/ai-mcp/tests/mcp-tool-source.test-d.ts
@@ -0,0 +1,8 @@
+import { expectTypeOf } from 'vitest'
+import type { MCPToolSource } from '@tanstack/ai'
+import type { MCPClient, MCPClients } from '../src'
+
+declare const client: MCPClient
+declare const pool: MCPClients
+expectTypeOf(client).toMatchTypeOf<MCPToolSource>()
+expectTypeOf(pool).toMatchTypeOf<MCPToolSource>()
diff --git a/packages/ai-mcp/tests/pool-chat.test.ts b/packages/ai-mcp/tests/pool-chat.test.ts
new file mode 100644
index 000000000..2a3bda1ed
--- /dev/null
+++ b/packages/ai-mcp/tests/pool-chat.test.ts
@@ -0,0 +1,129 @@
+/**
+ * Integration: a real `createMCPClients(...)` pool passed into `chat({ mcp })`.
+ *
+ * The chat-side unit tests (packages/ai) cover the `MCPToolSource` contract with
+ * fake sources, and `pool.test.ts` covers the pool's own `tools()`/`close()`.
+ * This wires the two together end-to-end: a live in-memory MCP server pool
+ * handed to `chat()` must have its (prefixed) tools discovered into the run and
+ * its connections closed when the run drains — proving the pool genuinely
+ * satisfies the `MCPToolSource` shape `chat({ mcp })` consumes.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { chat } from '@tanstack/ai'
+import type { AnyTextAdapter } from '@tanstack/ai'
+import { createMCPClients } from '../src/pool'
+import { makeServerWithWeatherTool } from './helpers/in-memory-server'
+
+/**
+ * Minimal text adapter: captures the tool names handed to `chatStream` (so we
+ * can assert the pool's tools were discovered + merged) and emits a complete
+ * AG-UI lifecycle so the engine finishes cleanly.
+ */
+function makeMockAdapter(
+  onTools: (names: Array<string>) => void,
+): AnyTextAdapter {
+  return {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~types': {
+      providerOptions: {},
+      inputModalities: ['text'],
+      messageMetadataByModality: {
+        text: undefined,
+        image: undefined,
+        audio: undefined,
+        video: undefined,
+        document: undefined,
+      },
+      toolCapabilities: [],
+      toolCallMetadata: undefined,
+      systemPromptMetadata: undefined,
+    },
+    chatStream: (opts: { tools?: Array<{ name: string }> }) => {
+      onTools((opts.tools ?? []).map((t) => t.name))
+      return (async function* () {
+        const ts = Date.now()
+        yield {
+          type: 'RUN_STARTED',
+          runId: 'r1',
+          threadId: 't1',
+          timestamp: ts,
+        }
+        yield {
+          type: 'TEXT_MESSAGE_START',
+          messageId: 'm1',
+          role: 'assistant',
+          timestamp: ts,
+        }
+        yield {
+          type: 'TEXT_MESSAGE_CONTENT',
+          messageId: 'm1',
+          delta: 'ok',
+          timestamp: ts,
+        }
+        yield { type: 'TEXT_MESSAGE_END', messageId: 'm1', timestamp: ts }
+        yield {
+          type: 'RUN_FINISHED',
+          runId: 'r1',
+          threadId: 't1',
+          finishReason: 'stop',
+          timestamp: ts,
+        }
+      })()
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  } as unknown as AnyTextAdapter
+}
+
+async function drain(stream: unknown): Promise<void> {
+  for await (const _chunk of stream as AsyncIterable<unknown>) {
+    // discard
+  }
+}
+
+describe('createMCPClients pool → chat({ mcp })', () => {
+  it("discovers the pool's prefixed tools and closes the pool after the run", async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    const pool = await createMCPClients({
+      weather: { transport: clientTransport },
+    })
+    const closeSpy = vi.spyOn(pool, 'close')
+
+    let seenTools: Array<string> = []
+    const adapter = makeMockAdapter((names) => {
+      seenTools = names
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hi' }],
+      mcp: { clients: [pool] },
+    })
+    await drain(stream)
+
+    // Pool tool was discovered + merged into the run (auto-prefixed by config key).
+    expect(seenTools).toContain('weather_get_weather')
+    // Default connection ('close') disposes the pool when the run drains.
+    expect(closeSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it("keep-alive: the pool is NOT closed when connection is 'keep-alive'", async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    const pool = await createMCPClients({
+      weather: { transport: clientTransport },
+    })
+    const closeSpy = vi.spyOn(pool, 'close')
+    const adapter = makeMockAdapter(() => {})
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hi' }],
+      mcp: { clients: [pool], connection: 'keep-alive' },
+    })
+    await drain(stream)
+
+    expect(closeSpy).not.toHaveBeenCalled()
+    await pool.close() // clean up the kept-alive connection
+  })
+})
diff --git a/packages/ai-mcp/tests/pool.test.ts b/packages/ai-mcp/tests/pool.test.ts
new file mode 100644
index 000000000..58b026f1f
--- /dev/null
+++ b/packages/ai-mcp/tests/pool.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { createMCPClients } from '../src/pool'
+import { makeServerWithWeatherTool } from './helpers/in-memory-server'
+
+describe('createMCPClients', () => {
+  it('connects to many servers and flattens auto-prefixed tools', async () => {
+    const a = await makeServerWithWeatherTool()
+    const b = await makeServerWithWeatherTool()
+    await using pool = await createMCPClients({
+      alpha: { transport: a.clientTransport },
+      beta: { transport: b.clientTransport },
+    })
+    const names = (await pool.tools()).map((t) => t.name)
+    expect(names).toContain('alpha_get_weather')
+    expect(names).toContain('beta_get_weather') // no collision despite same server tool name
+  })
+
+  it('exposes typed per-server access via .clients', async () => {
+    const a = await makeServerWithWeatherTool()
+    await using pool = await createMCPClients({
+      alpha: { transport: a.clientTransport },
+    })
+
+    expect(await pool.clients.alpha!.tools()).toBeDefined()
+  })
+
+  it('forwards ToolsOptions (lazy) to every server', async () => {
+    const a = await makeServerWithWeatherTool()
+    const b = await makeServerWithWeatherTool()
+    await using pool = await createMCPClients({
+      alpha: { transport: a.clientTransport },
+      beta: { transport: b.clientTransport },
+    })
+    const tools = await pool.tools({ lazy: true })
+    expect(tools.length).toBeGreaterThan(0)
+    expect(tools.every((t) => t.lazy === true)).toBe(true)
+  })
+
+  it('names the failing server by config key when tools() discovery fails', async () => {
+    const a = await makeServerWithWeatherTool()
+    const b = await makeServerWithWeatherTool()
+    const pool = await createMCPClients({
+      alpha: { transport: a.clientTransport },
+      beta: { transport: b.clientTransport },
+    })
+    // Force a per-server discovery failure after connect.
+
+    await pool.clients.beta!.close()
+    await expect(pool.tools()).rejects.toThrow(
+      /Failed to list tools from MCP server\(s\): beta/,
+    )
+    await pool.close()
+  })
+
+  it('closes already-connected clients and throws if one server fails', async () => {
+    const a = await makeServerWithWeatherTool()
+    // Wrap alpha's transport close so we can assert cleanup actually ran.
+    const originalClose = a.clientTransport.close.bind(a.clientTransport)
+    let alphaClosed = false
+    a.clientTransport.close = async () => {
+      alphaClosed = true
+      await originalClose()
+    }
+    const broken = {
+      start: async () => {
+        throw new Error('nope')
+      },
+      send: async () => {},
+      close: async () => {},
+    }
+    await expect(
+      createMCPClients({
+        alpha: { transport: a.clientTransport },
+        beta: { transport: broken as any },
+      }),
+    ).rejects.toThrow(/beta/)
+    expect(alphaClosed).toBe(true)
+  })
+})
diff --git a/packages/ai-mcp/tests/prompts.test.ts b/packages/ai-mcp/tests/prompts.test.ts
new file mode 100644
index 000000000..edf40ed3b
--- /dev/null
+++ b/packages/ai-mcp/tests/prompts.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+import { createMCPClientFromTransport } from '../src/client'
+import { mcpPromptToMessages } from '../src/prompts'
+import { makeServerWithPrompt } from './helpers/in-memory-server'
+
+describe('mcpPromptToMessages', () => {
+  it('converts a user text message correctly', () => {
+    const prompt = {
+      messages: [{ role: 'user', content: { type: 'text', text: 'review x' } }],
+    }
+    const messages = mcpPromptToMessages(prompt)
+
+    expect(messages).toHaveLength(1)
+    expect(messages[0]!.role).toBe('user')
+    expect(messages[0]!.content).toBe('review x')
+  })
+
+  it('maps assistant role correctly', () => {
+    const prompt = {
+      messages: [
+        { role: 'assistant', content: { type: 'text', text: 'looks good' } },
+      ],
+    }
+    const messages = mcpPromptToMessages(prompt)
+
+    expect(messages[0]!.role).toBe('assistant')
+    expect(messages[0]!.content).toBe('looks good')
+  })
+
+  it('falls back to JSON.stringify for non-text content', () => {
+    const content = { type: 'image', data: 'base64...' }
+    const prompt = {
+      messages: [{ role: 'user', content }],
+    }
+    const messages = mcpPromptToMessages(prompt)
+
+    expect(messages[0]!.content).toBe(JSON.stringify(content))
+  })
+
+  it('treats unknown roles as user', () => {
+    const prompt = {
+      messages: [{ role: 'system', content: { type: 'text', text: 'hi' } }],
+    }
+    const messages = mcpPromptToMessages(prompt)
+
+    expect(messages[0]!.role).toBe('user')
+  })
+})
+
+describe('MCPClient prompts integration', () => {
+  it('lists prompts and retrieves a prompt via the client', async () => {
+    await using client = await createMCPClientFromTransport(
+      (await makeServerWithPrompt()).clientTransport,
+    )
+
+    const list = await client.prompts()
+    expect(list.length).toBeGreaterThan(0)
+
+    const prompt = await client.getPrompt(list[0]!.name, { code: 'x = 1' })
+    const messages = mcpPromptToMessages(prompt)
+
+    expect(messages[0]).toHaveProperty('role')
+    expect(messages[0]).toHaveProperty('content')
+  })
+})
diff --git a/packages/ai-mcp/tests/resources.test.ts b/packages/ai-mcp/tests/resources.test.ts
new file mode 100644
index 000000000..6abf1fdd8
--- /dev/null
+++ b/packages/ai-mcp/tests/resources.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { createMCPClientFromTransport } from '../src/client'
+import { mcpResourceToContentPart } from '../src/resources'
+import { makeServerWithResource } from './helpers/in-memory-server'
+
+describe('mcpResourceToContentPart', () => {
+  it('converts a text content block to a TextPart', () => {
+    const part = mcpResourceToContentPart({ uri: 'file:///x', text: 'hello' })
+    expect(part.type).toBe('text')
+    expect((part as { type: 'text'; content: string }).content).toBe('hello')
+  })
+
+  it('converts a blob content block to a TextPart with binary placeholder', () => {
+    const part = mcpResourceToContentPart({
+      uri: 'file:///img.png',
+      blob: 'abc123',
+    })
+    expect(part.type).toBe('text')
+    expect((part as { type: 'text'; content: string }).content).toBe(
+      '[binary resource file:///img.png]',
+    )
+  })
+
+  it('falls back to JSON.stringify for unknown content', () => {
+    const input = {
+      uri: 'file:///unknown',
+      mimeType: 'application/octet-stream',
+    }
+    const part = mcpResourceToContentPart(input)
+    expect(part.type).toBe('text')
+    expect((part as { type: 'text'; content: string }).content).toBe(
+      JSON.stringify(input),
+    )
+  })
+})
+
+describe('MCPClient resource methods (connected)', () => {
+  it('resources() / readResource() round-trip via in-memory server', async () => {
+    await using client = await createMCPClientFromTransport(
+      (await makeServerWithResource()).clientTransport,
+    )
+
+    const list = await client.resources()
+    expect(list.length).toBeGreaterThan(0)
+
+    const read = await client.readResource(list[0]!.uri)
+    const part = mcpResourceToContentPart(read.contents[0]!)
+    expect(part.type).toBe('text')
+  })
+})
diff --git a/packages/ai-mcp/tests/stdio.test.ts b/packages/ai-mcp/tests/stdio.test.ts
new file mode 100644
index 000000000..d3d15c82b
--- /dev/null
+++ b/packages/ai-mcp/tests/stdio.test.ts
@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest'
+import { stdioTransport } from '../src/stdio'
+
+describe('stdioTransport', () => {
+  it('builds a Transport instance without starting it', () => {
+    const transport = stdioTransport({ command: 'node' })
+    expect(typeof transport.start).toBe('function')
+    expect(typeof transport.send).toBe('function')
+    expect(typeof transport.close).toBe('function')
+  })
+})
diff --git a/packages/ai-mcp/tests/tools.test.ts b/packages/ai-mcp/tests/tools.test.ts
new file mode 100644
index 000000000..3b7cd0de3
--- /dev/null
+++ b/packages/ai-mcp/tests/tools.test.ts
@@ -0,0 +1,170 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import {
+  makeMcpExecute,
+  mcpContentToTanstack,
+  toServerTools,
+} from '../src/tools'
+import {
+  makeServerWithFailingTool,
+  makeServerWithWeatherTool,
+} from './helpers/in-memory-server'
+
+describe('mcpContentToTanstack', () => {
+  it('returns a plain string for a single text block', () => {
+    expect(mcpContentToTanstack([{ type: 'text', text: 'hello' }])).toBe(
+      'hello',
+    )
+  })
+
+  it('maps multi-block arrays to ContentParts', () => {
+    expect(
+      mcpContentToTanstack([
+        { type: 'text', text: 'a' },
+        { type: 'text', text: 'b' },
+      ]),
+    ).toEqual([
+      { type: 'text', content: 'a' },
+      { type: 'text', content: 'b' },
+    ])
+  })
+
+  it('maps image blocks to data-source image parts', () => {
+    const image = { type: 'image', data: 'aGk=', mimeType: 'image/png' }
+    expect(
+      mcpContentToTanstack([image, { type: 'text', text: 'caption' }]),
+    ).toEqual([
+      {
+        type: 'image',
+        source: { type: 'data', value: 'aGk=', mimeType: 'image/png' },
+      },
+      { type: 'text', content: 'caption' },
+    ])
+  })
+
+  it('stringifies resource blocks as text parts', () => {
+    const resource = {
+      type: 'resource',
+      resource: { uri: 'file:///x.txt', text: 'x' },
+    }
+    expect(
+      mcpContentToTanstack([resource, { type: 'text', text: 'y' }]),
+    ).toEqual([
+      { type: 'text', content: JSON.stringify(resource.resource) },
+      { type: 'text', content: 'y' },
+    ])
+  })
+
+  it('stringifies unknown block types as text parts', () => {
+    const unknown = { type: 'audio', data: 'zzz' }
+    expect(
+      mcpContentToTanstack([unknown, { type: 'text', text: 'y' }]),
+    ).toEqual([
+      { type: 'text', content: JSON.stringify(unknown) },
+      { type: 'text', content: 'y' },
+    ])
+  })
+})
+
+describe('makeMcpExecute', () => {
+  it('throws an error naming the tool when the MCP tool returns isError', async () => {
+    const { clientTransport } = await makeServerWithFailingTool()
+    const client = new Client({ name: 'test', version: '1.0.0' })
+    await client.connect(clientTransport)
+    const defs = (await client.listTools()).tools
+    const tools = toServerTools(client, defs, {
+      prefix: undefined,
+      lazy: false,
+    })
+    const tool = tools.find((t) => t.name === 'always_fails')!
+    await expect(
+      tool.execute!({}, { toolCallId: 't', emitCustomEvent: () => {} }),
+    ).rejects.toThrow(/always_fails.*boom/)
+    await client.close()
+  })
+
+  it('forwards the abortSignal to client.callTool', async () => {
+    const callTool = vi
+      .fn()
+      .mockResolvedValue({ content: [{ type: 'text', text: 'ok' }] })
+    const client = { callTool } as unknown as Client
+    const controller = new AbortController()
+    const execute = makeMcpExecute(client, 'x', false)
+    await expect(execute({}, { abortSignal: controller.signal })).resolves.toBe(
+      'ok',
+    )
+    expect(callTool).toHaveBeenCalledWith(
+      { name: 'x', arguments: {} },
+      undefined,
+      { signal: controller.signal },
+    )
+  })
+
+  it('rejects without calling the server when the signal is already aborted', async () => {
+    const callTool = vi.fn()
+    const client = { callTool } as unknown as Client
+    const controller = new AbortController()
+    controller.abort()
+    const execute = makeMcpExecute(client, 'x', false)
+    await expect(
+      execute({}, { abortSignal: controller.signal }),
+    ).rejects.toThrow()
+    expect(callTool).not.toHaveBeenCalled()
+  })
+
+  it('prefers structuredContent when the tool declares an outputSchema', async () => {
+    const callTool = vi.fn().mockResolvedValue({
+      content: [{ type: 'text', text: '{"temperature":72}' }],
+      structuredContent: { temperature: 72 },
+    })
+    const client = { callTool } as unknown as Client
+    const execute = makeMcpExecute(client, 'x', true)
+    await expect(execute({})).resolves.toEqual({ temperature: 72 })
+  })
+
+  it('falls back to content[] when preferStructured is false', async () => {
+    const callTool = vi.fn().mockResolvedValue({
+      content: [{ type: 'text', text: 'plain' }],
+      structuredContent: { ignored: true },
+    })
+    const client = { callTool } as unknown as Client
+    const execute = makeMcpExecute(client, 'x', false)
+    await expect(execute({})).resolves.toBe('plain')
+  })
+})
+
+describe('toServerTools', () => {
+  it('discovers tools and proxies execute to callTool', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    const client = new Client({ name: 'test', version: '1.0.0' })
+    await client.connect(clientTransport)
+
+    const defs = (await client.listTools()).tools
+    const tools = toServerTools(client, defs, {
+      prefix: undefined,
+      lazy: false,
+    })
+
+    expect(tools.map((t) => t.name)).toContain('get_weather')
+    const tool = tools.find((t) => t.name === 'get_weather')!
+    const result = await tool.execute!(
+      { city: 'Brooklyn' },
+      {
+        toolCallId: 't',
+        emitCustomEvent: () => {},
+      },
+    )
+    expect(JSON.stringify(result)).toContain('Sunny in Brooklyn')
+    await client.close()
+  })
+
+  it('applies a prefix', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    const client = new Client({ name: 'test', version: '1.0.0' })
+    await client.connect(clientTransport)
+    const defs = (await client.listTools()).tools
+    const tools = toServerTools(client, defs, { prefix: 'wx', lazy: false })
+    expect(tools.map((t) => t.name)).toContain('wx_get_weather')
+    await client.close()
+  })
+})
diff --git a/packages/ai-mcp/tests/transport.test.ts b/packages/ai-mcp/tests/transport.test.ts
new file mode 100644
index 000000000..4034606d7
--- /dev/null
+++ b/packages/ai-mcp/tests/transport.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+import { resolveTransport } from '../src/transport'
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js'
+
+const fakeAuthProvider: OAuthClientProvider = {
+  redirectUrl: 'https://app.example.com/oauth/callback',
+  clientMetadata: { redirect_uris: ['https://app.example.com/oauth/callback'] },
+  clientInformation: () => undefined,
+  tokens: () => undefined,
+  saveTokens: () => {},
+  redirectToAuthorization: () => {},
+  saveCodeVerifier: () => {},
+  codeVerifier: () => 'verifier',
+}
+
+describe('resolveTransport', () => {
+  it('builds a Streamable HTTP transport from config', async () => {
+    const t = await resolveTransport({
+      type: 'http',
+      url: 'https://example.com/mcp',
+      headers: { Authorization: 'Bearer x' },
+    })
+    expect(t).toBeDefined()
+    expect(t.constructor.name).toMatch(/StreamableHTTP/)
+  })
+
+  it('forwards authProvider to the HTTP and SSE transports', async () => {
+    const http = await resolveTransport({
+      type: 'http',
+      url: 'https://example.com/mcp',
+      authProvider: fakeAuthProvider,
+    })
+    const sse = await resolveTransport({
+      type: 'sse',
+      url: 'https://example.com/sse',
+      authProvider: fakeAuthProvider,
+    })
+    // The SDK transports keep the provider in a private `_authProvider`
+    // field (no public getter). Pinning it here guards the option actually
+    // being forwarded; the field name is stable for the pinned SDK version.
+    expect(Reflect.get(http, '_authProvider')).toBe(fakeAuthProvider)
+    expect(Reflect.get(sse, '_authProvider')).toBe(fakeAuthProvider)
+  })
+
+  it('passes through a user-supplied transport instance', async () => {
+    const fake = {
+      start: async () => {},
+      send: async () => {},
+      close: async () => {},
+    }
+    const t = await resolveTransport(fake as any)
+    expect(t).toBe(fake)
+  })
+
+  it('throws a clear error for stdio without the /stdio import', async () => {
+    await expect(
+      resolveTransport({ type: 'stdio', command: 'node', args: [] }),
+    ).rejects.toThrow(/@tanstack\/ai-mcp\/stdio/)
+  })
+})
diff --git a/packages/ai-mcp/tests/types.test-d.ts b/packages/ai-mcp/tests/types.test-d.ts
new file mode 100644
index 000000000..b96885a36
--- /dev/null
+++ b/packages/ai-mcp/tests/types.test-d.ts
@@ -0,0 +1,40 @@
+import { expectTypeOf } from 'vitest'
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+import type { MCPClient } from '../src/client'
+import type { MappedServerTools, ServerDescriptor } from '../src/types'
+import type { ServerTool } from '@tanstack/ai'
+
+interface WeatherServer extends ServerDescriptor {
+  tools: { get_weather: { input: { city: string }; output: string } }
+  resources: {}
+  prompts: {}
+  capabilities: { tools: {} }
+}
+
+declare const client: MCPClient<WeatherServer>
+
+// Discovery: tools() (no args) resolves to typed ServerTools keyed by the
+// descriptor — an array whose element matches ServerTool, and whose `name`
+// is the descriptor's tool-name literal (the guarantee this path delivers;
+// args/results stay untyped on discovery).
+const discovered = await client.tools()
+expectTypeOf(discovered).toBeArray()
+expectTypeOf(discovered).items.toMatchTypeOf<ServerTool>()
+expectTypeOf(discovered).items.toMatchTypeOf<{ name: 'get_weather' }>()
+
+// Default (no generic): discovery still yields an array of ServerTool
+// (unchanged from before the descriptor overlay was added).
+declare const defaultClient: MCPClient
+const defaultDiscovered = await defaultClient.tools()
+expectTypeOf(defaultDiscovered).toBeArray()
+expectTypeOf(defaultDiscovered).items.toMatchTypeOf<ServerTool>()
+
+// Defs overload still yields per-def types via MappedServerTools.
+const getWeather = toolDefinition({
+  name: 'get_weather',
+  description: 'Get weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+})
+const bound = await client.tools([getWeather])
+expectTypeOf(bound).toEqualTypeOf<MappedServerTools<[typeof getWeather]>>()
diff --git a/packages/ai-mcp/tsconfig.json b/packages/ai-mcp/tsconfig.json
new file mode 100644
index 000000000..6e7ab980b
--- /dev/null
+++ b/packages/ai-mcp/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist" },
+  "include": ["src", "tests"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/ai-mcp/tsup.bin.config.ts b/packages/ai-mcp/tsup.bin.config.ts
new file mode 100644
index 000000000..e5635420d
--- /dev/null
+++ b/packages/ai-mcp/tsup.bin.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: { bin: 'src/cli/bin.ts' },
+  outDir: 'dist/bin',
+  format: ['esm'],
+  platform: 'node',
+  target: 'node18',
+  // Inline codegen-only deps into the bin so they aren't runtime deps of the lib.
+  noExternal: ['json-schema-to-typescript', 'jiti'],
+  // Keep the heavy SDK + workspace pkg external (installed alongside).
+  external: ['@modelcontextprotocol/sdk', '@tanstack/ai'],
+  banner: { js: '#!/usr/bin/env node' },
+})
diff --git a/packages/ai-mcp/vite.config.ts b/packages/ai-mcp/vite.config.ts
new file mode 100644
index 000000000..f428e9a09
--- /dev/null
+++ b/packages/ai-mcp/vite.config.ts
@@ -0,0 +1,28 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import { tanstackViteConfig } from '@tanstack/vite-config'
+import packageJson from './package.json'
+
+const config = defineConfig({
+  test: {
+    name: packageJson.name,
+    dir: './',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      include: ['src/**/*.ts'],
+      exclude: ['src/cli/**', '**/*.test.ts', 'src/types.ts'],
+    },
+  },
+})
+
+export default mergeConfig(
+  config,
+  tanstackViteConfig({
+    entry: ['./src/index.ts', './src/stdio.ts'],
+    srcDir: './src',
+    cjs: false,
+  }),
+)
diff --git a/packages/ai/skills/ai-core/chat-experience/SKILL.md b/packages/ai/skills/ai-core/chat-experience/SKILL.md
index 23bb293cf..8153bf739 100644
--- a/packages/ai/skills/ai-core/chat-experience/SKILL.md
+++ b/packages/ai/skills/ai-core/chat-experience/SKILL.md
@@ -310,6 +310,77 @@ const { messages, sendMessage } = useChat({
 The only difference is swapping `toServerSentEventsResponse` / `fetchServerSentEvents`
 for `toHttpResponse` / `fetchHttpStream`. Everything else stays identical.
 
+### 5. MCP Tool Discovery via `chat({ mcp })`
+
+Pass `mcp` to let `chat()` own discovery **and** lifecycle for one or more MCP
+clients. Useful when you want minimal boilerplate and don't need to reuse the
+clients across calls.
+
+```typescript
+// Prop shape:
+// chat({
+//   ...,
+//   mcp: {
+//     clients: Array<MCPClient | MCPClients>,
+//     connection?: 'close' | 'keep-alive',  // default: 'close'
+//     lazyTools?: boolean,
+//     onDiscoveryError?: (error: unknown, source) => void,
+//   }
+// })
+```
+
+- **`clients`** — one or more `MCPClient` / `MCPClients` instances.
+- **`connection`** — `'close'` (default) closes each client when the run ends
+  (after the agent loop completes and the stream is drained); with
+  `'keep-alive'`, `chat()` never closes the clients — the caller owns their
+  lifecycle (keep connections warm across requests).
+- **`lazyTools`** — forwarded to `tools({ lazy: true })` so tool schemas are
+  sent to the LLM on demand.
+- **`onDiscoveryError`** — throw (or re-throw) to fail the entire call fast;
+  return normally to skip that source and continue. Omit to rethrow (fail-fast).
+
+**When to use `mcp` vs. the tools spread:**
+
+| Approach                                                | Use when                                                                                        |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `chat({ mcp: { clients: [...] } })`                     | You want discovery + lifecycle managed for you, and don't need fully-typed input/output schemas |
+| `tools: [...await client.tools([toolDefinition(...)])]` | You want fully-typed MCP tools with Zod input/output validation                                 |
+
+**Server-side example:**
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        const mcpClient = await createMCPClient({
+          transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+        })
+
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          mcp: {
+            clients: [mcpClient],
+            connection: 'keep-alive', // chat() won't close it — reuse across requests
+          },
+        })
+
+        return toServerSentEventsResponse(stream)
+        // connection: 'keep-alive' — chat() never closes mcpClient; it stays open for reuse across runs.
+      },
+    },
+  },
+})
+```
+
 ## Common Mistakes
 
 ### a. CRITICAL: Using Vercel AI SDK patterns (streamText, generateText)
diff --git a/packages/ai/skills/ai-core/tool-calling/SKILL.md b/packages/ai/skills/ai-core/tool-calling/SKILL.md
index a72c94f36..98b905e9d 100644
--- a/packages/ai/skills/ai-core/tool-calling/SKILL.md
+++ b/packages/ai/skills/ai-core/tool-calling/SKILL.md
@@ -375,6 +375,213 @@ gets the full schema, then calls `compareProducts` directly.
 Once discovered, a tool stays available for the conversation.
 When all lazy tools are discovered, the discovery tool is removed automatically.
 
+## MCP Tools
+
+`@tanstack/ai-mcp` lets a server-side `chat()` call discover and invoke tools
+hosted on any MCP server (Streamable HTTP, SSE, or stdio).
+
+### Basic usage — auto-discovery
+
+```typescript
+// src/routes/api.chat.ts
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        // 1. Connect to the MCP server.
+        const mcp = await createMCPClient({
+          transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+        })
+
+        // 2. Discover all tools from the server (returns ServerTool[]).
+        const mcpTools = await mcp.tools()
+
+        // 3. Spread them into chat() — they work exactly like hand-written tools.
+        // Caller owns the lifecycle — chat() never closes the client. Tools run
+        // while the response streams, so close in a middleware terminal hook
+        // (a try/finally around the return would close before tools execute).
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          tools: [...mcpTools],
+          middleware: [
+            {
+              name: 'mcp-close',
+              onFinish: () => mcp.close(),
+              onAbort: () => mcp.close(),
+              onError: () => mcp.close(),
+            },
+          ],
+        })
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+### Typed path — pass toolDefinition instances
+
+Pass bare `toolDefinition()` instances (no `.server()`) to `client.tools([...])`.
+The MCP client supplies a `callTool` proxy as the execute function, while
+input/output validation and types come from the definitions' Zod schemas.
+
+```typescript
+import { toolDefinition } from '@tanstack/ai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { z } from 'zod'
+
+const getWeather = toolDefinition({
+  name: 'get_weather',
+  description: 'Current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+  outputSchema: z.object({ temperature: z.number(), conditions: z.string() }),
+})
+
+const mcp = await createMCPClient({
+  transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+})
+
+// Returns ServerTool[] typed to the definitions' input/output schemas.
+// Throws MCPToolNotFoundError if the server does not expose a tool with that name.
+const tools = await mcp.tools([getWeather])
+
+const stream = chat({ adapter: openaiText('gpt-5.5'), messages, tools })
+```
+
+### Multiple servers with `createMCPClients`
+
+```typescript
+import { createMCPClients } from '@tanstack/ai-mcp'
+
+// Each key becomes the default prefix for that server's tools.
+await using pool = await createMCPClients({
+  github: { transport: { type: 'http', url: 'https://mcp.github.com/mcp' } },
+  linear: { transport: { type: 'http', url: 'https://mcp.linear.app/mcp' } },
+})
+
+// Tools auto-prefixed: 'github_search_repos', 'linear_create_issue', etc.
+const tools = await pool.tools()
+
+const stream = chat({ adapter: openaiText('gpt-5.5'), messages, tools })
+```
+
+Use `pool.clients.<name>` for typed per-server access (resources, prompts, typed
+`tools([defs])` overload).
+
+### `ToolExecutionContext.abortSignal` — cancelling long-running tools
+
+Every server tool's execute function now receives `abortSignal` in its context.
+When the chat run aborts (e.g. the client disconnects or calls the run's
+`abortController`), the signal fires and any in-flight `callTool` call is
+cancelled automatically.
+
+You can also forward it from your own server tools:
+
+```typescript
+const longRunningTool = myToolDef.server(async (args, ctx) => {
+  // Forward to fetch, a DB query, or an MCP callTool call.
+  const response = await fetch('https://slow.api/data', {
+    signal: ctx?.abortSignal,
+  })
+  return response.json()
+})
+```
+
+MCP tools wire this automatically — `makeMcpExecute` passes `ctx?.abortSignal`
+as the `signal` option to `client.callTool(...)`, so MCP server calls cancel
+with the chat run without any extra code.
+
+### stdio transport (Node-only)
+
+```typescript
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { stdioTransport } from '@tanstack/ai-mcp/stdio'
+
+const mcp = await createMCPClient({
+  transport: stdioTransport({ command: 'npx', args: ['-y', 'my-mcp-server'] }),
+})
+```
+
+Import `stdioTransport` from the `/stdio` subpath only — it contains Node.js
+`child_process` imports and must not be bundled for edge runtimes.
+
+### `chat({ mcp })` — discovery + lifecycle in one prop
+
+Instead of manually calling `client.tools()` and managing `close()`, pass an
+`mcp` object and let `chat()` handle discovery and lifecycle.
+
+```typescript
+// Prop shape (ChatMCPOptions):
+// mcp: {
+//   clients: Array<MCPClient | MCPClients>,
+//   connection?: 'close' | 'keep-alive',  // default: 'close'
+//   lazyTools?: boolean,
+//   onDiscoveryError?: (error: unknown, source) => void,
+// }
+```
+
+- At run start, `chat()` calls `.tools()` on every entry in `clients` and merges
+  the results — identical to spreading `await client.tools()` into `tools: [...]`.
+- `lazyTools: true` is forwarded to `tools({ lazy: true })`.
+- `onDiscoveryError`: throw to fail-fast; return to skip that source.
+- `connection: 'close'` (default) closes each client when the run ends (after
+  the agent loop completes and the stream is drained). With `'keep-alive'`,
+  `chat()` never closes the clients — the caller owns their lifecycle (keep
+  connections warm across requests).
+
+**When to use `mcp` vs. the tools spread:**
+
+| Approach                                                | Use when                                                                          |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `chat({ mcp: { clients: [...] } })`                     | Convenience: discovery + lifecycle in one place; untyped tool args are acceptable |
+| `tools: [...await client.tools([toolDefinition(...)])]` | Fully-typed tool args/results via Zod schemas                                     |
+
+**Example:**
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        const mcpClient = await createMCPClient({
+          transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+        })
+
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          mcp: {
+            clients: [mcpClient],
+            connection: 'keep-alive',
+            onDiscoveryError: (err, source) => {
+              console.warn('MCP discovery failed, skipping source:', err)
+              // returning (not throwing) skips this source and continues
+            },
+          },
+        })
+
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
 ## Provider Skills
 
 > **Not to be confused with `@tanstack/ai-code-mode-skills`**, which are locally-generated TypeScript functions executed client-side. Provider Skills are hosted, provider-managed bundles that the model loads on demand and runs inside the provider's server-side sandbox.
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index a678a6ae9..eba41682f 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -25,6 +25,7 @@ import {
 import { maxIterations as maxIterationsStrategy } from './agent-loop-strategies'
 import { convertMessagesToModelMessages, generateMessageId } from './messages'
 import { MiddlewareRunner } from './middleware/compose'
+import { MCPManager } from './mcp/manager'
 import type {
   ApprovalRequest,
   ClientToolRequest,
@@ -69,6 +70,7 @@ import type {
   MergeContext,
   UnionToIntersection,
 } from './runtime-context-types'
+import type { ChatMCPOptions } from './mcp/types'
 
 // ===========================
 // Activity Kind
@@ -208,6 +210,12 @@ export interface TextActivityOptions<
         | ProviderTool<string, TAdapter['~types']['toolCapabilities'][number]>
       >
     | undefined
+  /**
+   * Hand MCP clients/pools to chat(): their tools are discovered at run start
+   * and merged into the run; `connection` controls whether chat() closes them
+   * when the run ends. See docs/tools/mcp.md "Managing MCP clients with chat()".
+   */
+  mcp?: ChatMCPOptions
   /** Additional metadata to attach to the request. */
   metadata?: TextOptions['metadata']
   /** Model-specific provider options (type comes from adapter) */
@@ -432,6 +440,28 @@ interface TextEngineConfig<
 type ToolPhaseResult = 'continue' | 'stop' | 'wait'
 type CyclePhase = 'processText' | 'executeToolCalls'
 
+/**
+ * Combine two optional AbortSignals into one that aborts when either does.
+ * Returns the other signal directly when one is absent or already aborted.
+ * (Manual implementation — `AbortSignal.any` requires Node >= 20.3.)
+ */
+function combineAbortSignals(
+  a: AbortSignal | undefined,
+  b: AbortSignal | undefined,
+): AbortSignal | undefined {
+  if (!a) return b
+  if (!b) return a
+  if (a.aborted) return a
+  if (b.aborted) return b
+  const controller = new AbortController()
+  const onAbort = (source: AbortSignal) => () => {
+    controller.abort(source.reason)
+  }
+  a.addEventListener('abort', onAbort(a), { once: true })
+  b.addEventListener('abort', onAbort(b), { once: true })
+  return controller.signal
+}
+
 class TextEngine<
   TAdapter extends AnyTextAdapter,
   TContext = unknown,
@@ -486,6 +516,9 @@ class TextEngine<
   private readonly deferredPromises: Array<Promise<unknown>> = []
   private abortReason?: string
   private readonly middlewareAbortController?: AbortController
+  // Combines the caller's signal with middleware abort() so running tools
+  // observe both cancellation sources via ctx.abortSignal.
+  private readonly toolAbortSignal?: AbortSignal
   private terminalHookCalled = false
 
   private readonly logger: InternalLogger
@@ -583,6 +616,10 @@ class TextEngine<
     ]
     this.middlewareRunner = new MiddlewareRunner(allMiddleware, logger)
     this.middlewareAbortController = new AbortController()
+    this.toolAbortSignal = combineAbortSignals(
+      this.effectiveSignal,
+      this.middlewareAbortController.signal,
+    )
     this.middlewareCtx = {
       requestId: this.requestId,
       streamId: this.streamId,
@@ -1225,6 +1262,7 @@ class TextEngine<
         },
       },
       this.middlewareCtx.context,
+      this.toolAbortSignal,
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -1386,6 +1424,7 @@ class TextEngine<
         },
       },
       this.middlewareCtx.context,
+      this.toolAbortSignal,
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -2568,10 +2607,16 @@ export function chat<
 async function* runStreamingText<TContext = unknown>(
   options: TextActivityOptions<AnyTextAdapter, undefined, true, TContext>,
 ): AsyncIterable<StreamChunk> {
-  const { adapter, middleware, context, debug, ...textOptions } = options
+  const { adapter, middleware, context, debug, mcp, ...textOptions } = options
   const model = adapter.model
   const logger = resolveDebugOption(debug)
 
+  const mcpManager = MCPManager.from(mcp)
+  const mcpTools = await mcpManager.discover()
+  if (mcpTools.length > 0) {
+    textOptions.tools = [...(textOptions.tools ?? []), ...mcpTools]
+  }
+
   const engine = new TextEngine(
     {
       adapter,
@@ -2586,8 +2631,12 @@ async function* runStreamingText<TContext = unknown>(
     logger,
   )
 
-  for await (const chunk of engine.run()) {
-    yield chunk
+  try {
+    for await (const chunk of engine.run()) {
+      yield chunk
+    }
+  } finally {
+    await mcpManager.dispose()
   }
 }
 
@@ -2624,8 +2673,15 @@ async function runAgenticStructuredOutput<
 >(
   options: TextActivityOptions<AnyTextAdapter, TSchema, boolean, TContext>,
 ): Promise<InferSchemaType<TSchema>> {
-  const { adapter, outputSchema, middleware, context, debug, ...textOptions } =
-    options
+  const {
+    adapter,
+    outputSchema,
+    middleware,
+    context,
+    debug,
+    mcp,
+    ...textOptions
+  } = options
   const model = adapter.model
   const logger = resolveDebugOption(debug)
 
@@ -2659,6 +2715,12 @@ async function runAgenticStructuredOutput<
   const nativeCombined =
     adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true
 
+  const mcpManager = MCPManager.from(mcp)
+  const mcpTools = await mcpManager.discover()
+  if (mcpTools.length > 0) {
+    textOptions.tools = [...(textOptions.tools ?? []), ...mcpTools]
+  }
+
   const engine = new TextEngine(
     {
       adapter,
@@ -2679,9 +2741,13 @@ async function runAgenticStructuredOutput<
     logger,
   )
 
-  // Consume the stream — chunks pipe through middleware but are not yielded externally
-  for await (const _chunk of engine.run()) {
-    // intentionally empty
+  try {
+    // Consume the stream — chunks pipe through middleware but are not yielded externally
+    for await (const _chunk of engine.run()) {
+      // intentionally empty
+    }
+  } finally {
+    await mcpManager.dispose()
   }
 
   const finalizationError = engine.getFinalizationError()
@@ -2912,8 +2978,15 @@ async function* runStreamingStructuredOutputImpl<
   options: TextActivityOptions<AnyTextAdapter, TSchema, true, TContext>,
   jsonSchema: NonNullable<ReturnType<typeof convertSchemaToJsonSchema>>,
 ): StructuredOutputStreamInternal<InferSchemaType<TSchema>> {
-  const { adapter, outputSchema, middleware, context, debug, ...textOptions } =
-    options
+  const {
+    adapter,
+    outputSchema,
+    middleware,
+    context,
+    debug,
+    mcp,
+    ...textOptions
+  } = options
   const model = adapter.model
   const logger = resolveDebugOption(debug)
 
@@ -2927,6 +3000,12 @@ async function* runStreamingStructuredOutputImpl<
   const nativeCombined =
     adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true
 
+  const mcpManager = MCPManager.from(mcp)
+  const mcpTools = await mcpManager.discover()
+  if (mcpTools.length > 0) {
+    textOptions.tools = [...(textOptions.tools ?? []), ...mcpTools]
+  }
+
   // Inputs may be UIMessages (from useChat) or ModelMessages (from server-side
   // callers). TextEngine handles the conversion uniformly.
   const engine = new TextEngine(
@@ -2948,8 +3027,12 @@ async function* runStreamingStructuredOutputImpl<
     logger,
   )
 
-  for await (const chunk of engine.run()) {
-    yield chunk
+  try {
+    for await (const chunk of engine.run()) {
+      yield chunk
+    }
+  } finally {
+    await mcpManager.dispose()
   }
 
   // Schema validation for the streaming variant remains the consumer's
diff --git a/packages/ai/src/activities/chat/mcp/manager.ts b/packages/ai/src/activities/chat/mcp/manager.ts
new file mode 100644
index 000000000..0ed8f19f7
--- /dev/null
+++ b/packages/ai/src/activities/chat/mcp/manager.ts
@@ -0,0 +1,85 @@
+import type { ServerTool } from '../tools/tool-definition'
+import type { ChatMCPOptions, MCPToolSource } from './types'
+
+export class MCPDuplicateToolNameError extends Error {
+  constructor(public readonly toolName: string) {
+    super(
+      `Duplicate MCP tool name "${toolName}" in chat({ mcp.clients }). ` +
+        `Set a unique \`prefix\` on one of the MCP clients (or use a pool, ` +
+        `which auto-prefixes) to disambiguate.`,
+    )
+    this.name = 'MCPDuplicateToolNameError'
+  }
+}
+
+/**
+ * Encapsulates MCP tool discovery + connection lifecycle for chat().
+ * Built from chat()'s `mcp` option; runners only call `discover()` then
+ * `dispose()`. A manager built from `undefined` is an inert no-op
+ * (`discover()` → `[]`, `dispose()` → no-op), so runners need no branching.
+ */
+export class MCPManager {
+  static from(options: ChatMCPOptions | undefined): MCPManager {
+    return new MCPManager(options)
+  }
+
+  readonly #sources: ReadonlyArray<MCPToolSource>
+  readonly #shouldClose: boolean
+  readonly #lazyTools: boolean
+  readonly #onDiscoveryError?: (
+    error: unknown,
+    source: MCPToolSource,
+  ) => void | Promise<void>
+
+  private constructor(options: ChatMCPOptions | undefined) {
+    this.#sources = options?.clients ?? []
+    // default 'close'; only 'keep-alive' disables closing
+    this.#shouldClose = options ? options.connection !== 'keep-alive' : false
+    this.#lazyTools = options?.lazyTools ?? false
+    this.#onDiscoveryError = options?.onDiscoveryError
+  }
+
+  /**
+   * Discover + merge tools from all sources. Throws on a fatal discovery error
+   * (no `onDiscoveryError`, or it re-threw) or a duplicate tool name; in that
+   * case it first closes any connected sources when the policy is 'close'.
+   */
+  async discover(): Promise<Array<ServerTool>> {
+    if (this.#sources.length === 0) return []
+    try {
+      const settled = await Promise.allSettled(
+        this.#sources.map((s) => s.tools({ lazy: this.#lazyTools })),
+      )
+      const tools: Array<ServerTool> = []
+      const zipped = this.#sources.map(
+        (source, i) => [source, settled[i]] as const,
+      )
+      for (const [source, result] of zipped) {
+        if (result === undefined) continue
+        if (result.status === 'fulfilled') {
+          tools.push(...result.value)
+        } else if (this.#onDiscoveryError) {
+          // throw/reject inside handler ⇒ propagate (fail-fast); return ⇒ skip
+          await this.#onDiscoveryError(result.reason, source)
+        } else {
+          throw result.reason
+        }
+      }
+      const seen = new Set<string>()
+      for (const t of tools) {
+        if (seen.has(t.name)) throw new MCPDuplicateToolNameError(t.name)
+        seen.add(t.name)
+      }
+      return tools
+    } catch (err) {
+      await this.dispose() // cleanup-on-failure (no-op if keep-alive)
+      throw err
+    }
+  }
+
+  /** Close sources iff policy is 'close'. Idempotent; never throws. */
+  async dispose(): Promise<void> {
+    if (!this.#shouldClose || this.#sources.length === 0) return
+    await Promise.allSettled(this.#sources.map((s) => s.close()))
+  }
+}
diff --git a/packages/ai/src/activities/chat/mcp/types.ts b/packages/ai/src/activities/chat/mcp/types.ts
new file mode 100644
index 000000000..4e18b8ac6
--- /dev/null
+++ b/packages/ai/src/activities/chat/mcp/types.ts
@@ -0,0 +1,66 @@
+import type { ServerTool } from '../tools/tool-definition'
+
+/**
+ * Minimal structural shape that `chat({ mcp })` needs from an MCP client.
+ *
+ * `@tanstack/ai-mcp`'s `MCPClient` and `MCPClients` satisfy this interface by
+ * shape — the core `@tanstack/ai` package does NOT import `@tanstack/ai-mcp`
+ * (ai-mcp depends on ai, not the reverse).
+ */
+export interface MCPToolSource {
+  // Keep the options shape in sync with ai-mcp's `ToolsOptions` — extra
+  // optional fields added there still match structurally, but chat() only
+  // forwards what is declared here.
+  tools: (options?: { lazy?: boolean }) => Promise<Array<ServerTool>>
+  close: () => Promise<void>
+}
+
+/**
+ * Controls what happens to MCP connections when the chat run ends.
+ *
+ * - `'close'` (default) — `chat()` closes each connection when the run ends
+ *   (after the agent loop completes and the stream is drained), so tools can
+ *   still execute throughout the run.
+ * - `'keep-alive'` — `chat()` never closes the connections; the caller owns
+ *   their lifecycle (e.g. keep them warm across requests).
+ */
+export type MCPConnectionPolicy = 'close' | 'keep-alive'
+
+/**
+ * Options controlling MCP tool discovery and lifecycle for a `chat()` call.
+ */
+export interface ChatMCPOptions {
+  /**
+   * The MCP clients or client pools to discover tools from and manage.
+   */
+  clients: Array<MCPToolSource>
+
+  /**
+   * Connection lifecycle policy applied to all clients when the run ends.
+   *
+   * Defaults to `'close'`.
+   */
+  connection?: MCPConnectionPolicy
+
+  /**
+   * When `true`, tool schemas are fetched lazily (forwarded to
+   * `tools({ lazy: true })`).
+   *
+   * Defaults to `false`.
+   */
+  lazyTools?: boolean
+
+  /**
+   * Called when tool discovery fails for a single source.
+   *
+   * - Throw (or re-throw) from this handler to fail the entire chat call fast.
+   * - Return normally to skip that source and continue with remaining clients.
+   * - Omit this handler entirely to rethrow the error (fail-fast by default).
+   *
+   * Async handlers are awaited, so a rejected promise also fails fast.
+   */
+  onDiscoveryError?: (
+    error: unknown,
+    source: MCPToolSource,
+  ) => void | Promise<void>
+}
diff --git a/packages/ai/src/activities/chat/tools/tool-calls.ts b/packages/ai/src/activities/chat/tools/tool-calls.ts
index 9ab977cf9..4d5989d29 100644
--- a/packages/ai/src/activities/chat/tools/tool-calls.ts
+++ b/packages/ai/src/activities/chat/tools/tool-calls.ts
@@ -599,6 +599,7 @@ export async function* executeToolCalls<TContext = unknown>(
   ) => CustomEvent,
   middlewareHooks?: ToolExecutionMiddlewareHooks,
   userContext?: TContext,
+  abortSignal?: AbortSignal,
 ): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
@@ -679,6 +680,7 @@ export async function* executeToolCalls<TContext = unknown>(
     const context = {
       toolCallId: toolCall.id,
       context: userContext,
+      abortSignal,
       emitCustomEvent: (eventName: string, value: Record<string, any>) => {
         if (createCustomEventChunk) {
           pendingEvents.push(
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index c406290ea..dbb38722b 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -52,6 +52,16 @@ export {
   type InferToolOutput,
 } from './activities/chat/tools/tool-definition'
 
+// MCP chat option types
+export type {
+  MCPToolSource,
+  ChatMCPOptions,
+  MCPConnectionPolicy,
+} from './activities/chat/mcp/types'
+
+// MCP error classes (value exports — usable with instanceof)
+export { MCPDuplicateToolNameError } from './activities/chat/mcp/manager'
+
 // Schema conversion (Standard JSON Schema compliant)
 export {
   convertSchemaToJsonSchema,
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 29b1c8032..e57f860ba 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -490,6 +490,12 @@ export type ToolExecutionContext<TContext = unknown> =
   RuntimeContextField<TContext> & {
     /** The ID of the tool call being executed */
     toolCallId?: string
+    /**
+     * Abort signal for the current chat run. Aborts when the run's
+     * `abortController` fires (or middleware aborts). Long-running tools —
+     * e.g. MCP `callTool` — should forward this to cancel in-flight work.
+     */
+    abortSignal?: AbortSignal
     /**
      * Emit a custom event during tool execution.
      * Events are streamed to the client in real-time as AG-UI CUSTOM events.
diff --git a/packages/ai/tests/chat-mcp-manager.test.ts b/packages/ai/tests/chat-mcp-manager.test.ts
new file mode 100644
index 000000000..15cca96e6
--- /dev/null
+++ b/packages/ai/tests/chat-mcp-manager.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  MCPDuplicateToolNameError,
+  MCPManager,
+} from '../src/activities/chat/mcp/manager'
+import type { ServerTool } from '../src'
+
+function tool(name: string): ServerTool {
+  return {
+    __toolSide: 'server',
+    name,
+    description: '',
+    inputSchema: { type: 'object', properties: {} },
+    execute: async () => 'ok',
+  }
+}
+
+function source(tools: Array<ServerTool>, opts: { fail?: boolean } = {}) {
+  const s = {
+    closed: false,
+    tools: async (_o?: { lazy?: boolean }) => {
+      if (opts.fail) throw new Error('discovery failed')
+      return tools
+    },
+    close: async () => {
+      s.closed = true
+    },
+  }
+  return s
+}
+
+describe('MCPManager', () => {
+  it('no-op when built from undefined', async () => {
+    const m = MCPManager.from(undefined)
+    expect(await m.discover()).toEqual([])
+    await m.dispose() // no throw
+  })
+
+  it('discover() merges tools and forwards lazyTools', async () => {
+    const a = source([tool('a')])
+    const b = source([tool('b')])
+    const spyA = vi.spyOn(a, 'tools')
+    const m = MCPManager.from({ clients: [a, b], lazyTools: true })
+    expect((await m.discover()).map((t) => t.name)).toEqual(['a', 'b'])
+    expect(spyA).toHaveBeenCalledWith({ lazy: true })
+  })
+
+  it('discover() throws MCPDuplicateToolNameError on collision', async () => {
+    const m = MCPManager.from({
+      clients: [source([tool('x')]), source([tool('x')])],
+    })
+    await expect(m.discover()).rejects.toBeInstanceOf(MCPDuplicateToolNameError)
+  })
+
+  it('default connection closes sources on dispose()', async () => {
+    const a = source([tool('a')])
+    const m = MCPManager.from({ clients: [a] })
+    await m.discover()
+    await m.dispose()
+    expect(a.closed).toBe(true)
+  })
+
+  it("connection 'keep-alive' does NOT close on dispose()", async () => {
+    const a = source([tool('a')])
+    const m = MCPManager.from({ clients: [a], connection: 'keep-alive' })
+    await m.discover()
+    await m.dispose()
+    expect(a.closed).toBe(false)
+  })
+
+  it('rethrows by default on discovery failure and self-cleans (close policy)', async () => {
+    const a = source([tool('a')])
+    const b = source([], { fail: true })
+    const m = MCPManager.from({ clients: [a, b] }) // default close
+    await expect(m.discover()).rejects.toThrow('discovery failed')
+    expect(a.closed).toBe(true) // cleanup-on-failure
+  })
+
+  it('onDiscoveryError returning skips the failed source', async () => {
+    const onDiscoveryError = vi.fn()
+    const m = MCPManager.from({
+      clients: [source([tool('a')]), source([], { fail: true })],
+      onDiscoveryError,
+    })
+    expect((await m.discover()).map((t) => t.name)).toEqual(['a'])
+    expect(onDiscoveryError).toHaveBeenCalledOnce()
+  })
+
+  it('onDiscoveryError throwing propagates', async () => {
+    const m = MCPManager.from({
+      clients: [source([], { fail: true })],
+      onDiscoveryError: () => {
+        throw new Error('abort')
+      },
+    })
+    await expect(m.discover()).rejects.toThrow('abort')
+  })
+})
diff --git a/packages/ai/tests/chat-mcp-types.test-d.ts b/packages/ai/tests/chat-mcp-types.test-d.ts
new file mode 100644
index 000000000..66cd66d3a
--- /dev/null
+++ b/packages/ai/tests/chat-mcp-types.test-d.ts
@@ -0,0 +1,9 @@
+import { expectTypeOf } from 'vitest'
+import type { MCPToolSource } from '../src'
+
+// A plain object with tools()/close() satisfies the structural interface.
+const fake = {
+  tools: async () => [],
+  close: async () => {},
+}
+expectTypeOf(fake).toMatchTypeOf<MCPToolSource>()
diff --git a/packages/ai/tests/chat-mcp.test.ts b/packages/ai/tests/chat-mcp.test.ts
new file mode 100644
index 000000000..8acf9dc44
--- /dev/null
+++ b/packages/ai/tests/chat-mcp.test.ts
@@ -0,0 +1,566 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { chat } from '../src/activities/chat/index'
+import { MCPDuplicateToolNameError } from '../src/activities/chat/mcp/manager'
+import { collectChunks, createMockAdapter, ev } from './test-utils'
+import type { StreamChunk } from '../src/types'
+import type { MCPToolSource } from '../src/activities/chat/mcp/types'
+import type { ServerTool } from '../src/activities/chat/tools/tool-definition'
+
+// ============================================================================
+// Fake MCP source factory
+// ============================================================================
+
+interface FakeSourceOpts {
+  /** When true, tools() rejects with an error */
+  fail?: boolean
+  /** When true, tools() resolves but close() is counted separately */
+  failClose?: boolean
+}
+
+function fakeSource(
+  toolNames: ReadonlyArray<string>,
+  opts?: FakeSourceOpts,
+): MCPToolSource & {
+  readonly closed: boolean
+  readonly toolCallCount: number
+} {
+  let closed = false
+  let toolCallCount = 0
+
+  const source = {
+    get closed() {
+      return closed
+    },
+    get toolCallCount() {
+      return toolCallCount
+    },
+    tools: (options?: { lazy?: boolean }): Promise<Array<ServerTool>> => {
+      toolCallCount++
+      if (opts?.fail) {
+        return Promise.reject(
+          new Error(`discovery failed for ${toolNames[0] ?? 'unknown'}`),
+        )
+      }
+      const tools: Array<ServerTool> = toolNames.map(
+        (name) =>
+          ({
+            __toolSide: 'server' as const,
+            name,
+            description: `MCP tool: ${name}`,
+            execute: (_args: unknown) => ({ mcp: true, tool: name }),
+          }) satisfies ServerTool,
+      )
+      // Spy-able: caller can inspect toolCallCount and options via the spy wrapping tools()
+      void options // used by spy in lazyTools test
+      return Promise.resolve(tools)
+    },
+    close: async (): Promise<void> => {
+      closed = true
+    },
+  }
+  return source
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe('chat({ mcp })', () => {
+  // --------------------------------------------------------------------------
+  // Case 1: default connection:'close' closes every source after stream drains
+  // --------------------------------------------------------------------------
+  it('default connection closes sources after stream drains normally', async () => {
+    const source = fakeSource(['mcpTool'])
+
+    const { adapter } = createMockAdapter({
+      iterations: [
+        [
+          ev.runStarted(),
+          ev.textStart(),
+          ev.textContent('hi'),
+          ev.textEnd(),
+          ev.runFinished('stop'),
+        ],
+      ],
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hello' }],
+      mcp: { clients: [source] },
+    })
+
+    expect(source.closed).toBe(false)
+    await collectChunks(stream as AsyncIterable<StreamChunk>)
+    expect(source.closed).toBe(true)
+  })
+
+  // --------------------------------------------------------------------------
+  // Case 2: connection:'keep-alive' does NOT close sources
+  // --------------------------------------------------------------------------
+  it("connection:'keep-alive' does not close sources", async () => {
+    const source = fakeSource(['mcpTool'])
+
+    const { adapter } = createMockAdapter({
+      iterations: [
+        [
+          ev.runStarted(),
+          ev.textStart(),
+          ev.textContent('hi'),
+          ev.textEnd(),
+          ev.runFinished('stop'),
+        ],
+      ],
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hello' }],
+      mcp: { clients: [source], connection: 'keep-alive' },
+    })
+
+    await collectChunks(stream as AsyncIterable<StreamChunk>)
+    expect(source.closed).toBe(false)
+  })
+
+  // --------------------------------------------------------------------------
+  // Case 3: close fires on ERROR (adapter throws) — source is closed
+  // --------------------------------------------------------------------------
+  it('source is closed when the adapter stream throws an error', async () => {
+    const source = fakeSource(['mcpTool'])
+
+    const { adapter } = createMockAdapter({
+      chatStreamFn: () =>
+        (async function* (): AsyncIterable<StreamChunk> {
+          yield ev.runStarted()
+          throw new Error('adapter boom')
+        })(),
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hello' }],
+      mcp: { clients: [source] },
+    })
+
+    await expect(
+      collectChunks(stream as AsyncIterable<StreamChunk>),
+    ).rejects.toThrow('adapter boom')
+
+    expect(source.closed).toBe(true)
+  })
+
+  // --------------------------------------------------------------------------
+  // Case 4: close fires on ABORT — source is closed after stream ends
+  // --------------------------------------------------------------------------
+  it('source is closed when the run is aborted mid-stream', async () => {
+    const source = fakeSource(['mcpTool'])
+    const abortController = new AbortController()
+
+    const { adapter } = createMockAdapter({
+      chatStreamFn: () =>
+        (async function* (): AsyncIterable<StreamChunk> {
+          yield ev.runStarted()
+          yield ev.textStart()
+          yield ev.textContent('chunk1')
+          yield ev.textContent('chunk2')
+          yield ev.textContent('chunk3')
+          yield ev.textEnd()
+          yield ev.runFinished('stop')
+        })(),
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hello' }],
+      mcp: { clients: [source] },
+      abortController,
+    })
+
+    let count = 0
+    for await (const _chunk of stream as AsyncIterable<StreamChunk>) {
+      count++
+      if (count === 2) {
+        abortController.abort()
+      }
+    }
+
+    // Stream drained (early) — the finally block must have run
+    expect(source.closed).toBe(true)
+  })
+
+  // --------------------------------------------------------------------------
+  // Case 5: discovered tools reach the run and execute
+  // --------------------------------------------------------------------------
+  it('discovered MCP tools are merged into the run and execute when called', async () => {
+    const mcpExecuteSpy = vi.fn().mockReturnValue({ mcp: true, result: 'ok' })
+    const source: MCPToolSource = {
+      tools: async () => [
+        {
+          __toolSide: 'server' as const,
+          name: 'mcpGetData',
+          description: 'Fetches data via MCP',
+          execute: mcpExecuteSpy,
+        } satisfies ServerTool,
+      ],
+      close: async () => {},
+    }
+
+    const { adapter } = createMockAdapter({
+      iterations: [
+        // First iteration: model calls the MCP-discovered tool
+        [
+          ev.runStarted(),
+          ev.toolStart('call_mcp', 'mcpGetData'),
+          ev.toolArgs('call_mcp', '{"id":"42"}'),
+          ev.runFinished('tool_calls'),
+        ],
+        // Second iteration: model produces final text
+        [
+          ev.runStarted(),
+          ev.textStart(),
+          ev.textContent('Data fetched.'),
+          ev.textEnd(),
+          ev.runFinished('stop'),
+        ],
+      ],
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Get data' }],
+      mcp: { clients: [source] },
+    })
+
+    const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
+
+    // The MCP tool execute function ran
+    expect(mcpExecuteSpy).toHaveBeenCalledTimes(1)
+    expect(mcpExecuteSpy).toHaveBeenCalledWith(
+      { id: '42' },
+      expect.objectContaining({ toolCallId: 'call_mcp' }),
+    )
+
+    // There should be a tool result chunk in the stream
+    const toolResultChunks = chunks.filter(
+      (c) =>
+        c.type === 'TOOL_CALL_RESULT' && 'content' in c && (c as any).content,
+    )
+    expect(toolResultChunks.length).toBeGreaterThanOrEqual(1)
+  })
+
+  // --------------------------------------------------------------------------
+  // Case 6: lazyTools:true is forwarded to source.tools({ lazy: true })
+  // --------------------------------------------------------------------------
+  it('lazyTools:true is forwarded as { lazy: true } to source.tools()', async () => {
+    const toolsSpy = vi.fn().mockResolvedValue([
+      {
+        __toolSide: 'server' as const,
+        name: 'lazyMcpTool',
+        description: 'lazy tool',
+        execute: () => ({ ok: true }),
+      } satisfies ServerTool,
+    ])
+
+    const source: MCPToolSource = {
+      tools: toolsSpy,
+      close: async () => {},
+    }
+
+    const { adapter } = createMockAdapter({
+      iterations: [
+        [
+          ev.runStarted(),
+          ev.textStart(),
+          ev.textContent('ok'),
+          ev.textEnd(),
+          ev.runFinished('stop'),
+        ],
+      ],
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hi' }],
+      mcp: { clients: [source], lazyTools: true },
+    })
+
+    await collectChunks(stream as AsyncIterable<StreamChunk>)
+
+    expect(toolsSpy).toHaveBeenCalledTimes(1)
+    expect(toolsSpy).toHaveBeenCalledWith({ lazy: true })
+  })
+
+  // --------------------------------------------------------------------------
+  // Case 7a: onDiscoveryError returning skips failed source, run proceeds
+  // --------------------------------------------------------------------------
+  it('onDiscoveryError returning skips the failed source and run proceeds', async () => {
+    const failingSource = fakeSource(['willFail'], { fail: true })
+    const goodSource = fakeSource(['goodTool'])
+    const errorHandler = vi.fn()
+
+    const { adapter } = createMockAdapter({
+      iterations: [
+        [
+          ev.runStarted(),
+          ev.textStart(),
+          ev.textContent('ok'),
+          ev.textEnd(),
+          ev.runFinished('stop'),
+        ],
+      ],
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hi' }],
+      mcp: {
+        clients: [failingSource, goodSource],
+        onDiscoveryError: errorHandler,
+      },
+    })
+
+    // Run completes without throwing
+    const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
+    expect(chunks.some((c) => c.type === 'RUN_FINISHED')).toBe(true)
+
+    // Error handler was called for the failing source
+    expect(errorHandler).toHaveBeenCalledTimes(1)
+    expect(errorHandler.mock.calls[0]![0]).toBeInstanceOf(Error)
+  })
+
+  // --------------------------------------------------------------------------
+  // Case 7b: onDiscoveryError throwing causes chat() to reject
+  // --------------------------------------------------------------------------
+  it('onDiscoveryError throwing causes chat() to reject', async () => {
+    const failingSource = fakeSource(['willFail'], { fail: true })
+
+    const { adapter } = createMockAdapter({
+      iterations: [],
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hi' }],
+      mcp: {
+        clients: [failingSource],
+        onDiscoveryError: (_err: unknown) => {
+          throw new Error('fatal discovery')
+        },
+      },
+    })
+
+    await expect(
+      collectChunks(stream as AsyncIterable<StreamChunk>),
+    ).rejects.toThrow('fatal discovery')
+  })
+
+  // --------------------------------------------------------------------------
+  // Case 8a: Duplicate tool name across sources rejects with MCPDuplicateToolNameError
+  // --------------------------------------------------------------------------
+  it('duplicate MCP tool name rejects with MCPDuplicateToolNameError', async () => {
+    const source1 = fakeSource(['sharedTool'])
+    const source2 = fakeSource(['sharedTool'])
+
+    const { adapter } = createMockAdapter({ iterations: [] })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hi' }],
+      mcp: { clients: [source1, source2] },
+    })
+
+    await expect(
+      collectChunks(stream as AsyncIterable<StreamChunk>),
+    ).rejects.toBeInstanceOf(MCPDuplicateToolNameError)
+  })
+
+  // --------------------------------------------------------------------------
+  // Case 8b: cleanup-on-failure — sources that connected are closed when discovery throws
+  // --------------------------------------------------------------------------
+  it('cleanup-on-failure: connected sources are closed when duplicate tool name is detected', async () => {
+    const source1 = fakeSource(['dupTool'])
+    const source2 = fakeSource(['dupTool'])
+
+    const { adapter } = createMockAdapter({ iterations: [] })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hi' }],
+      mcp: { clients: [source1, source2] },
+    })
+
+    await expect(
+      collectChunks(stream as AsyncIterable<StreamChunk>),
+    ).rejects.toBeInstanceOf(MCPDuplicateToolNameError)
+
+    // The duplicate error triggers dispose() — both sources get closed
+    expect(source1.closed).toBe(true)
+    expect(source2.closed).toBe(true)
+  })
+
+  // --------------------------------------------------------------------------
+  // Case 8c: cleanup-on-failure under default close when error is thrown directly
+  // --------------------------------------------------------------------------
+  it('cleanup-on-failure: sources that connected are closed when onDiscoveryError throws', async () => {
+    const goodSource = fakeSource(['goodTool'])
+    const failSource = fakeSource(['badTool'], { fail: true })
+
+    const { adapter } = createMockAdapter({ iterations: [] })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hi' }],
+      mcp: {
+        clients: [goodSource, failSource],
+        // No onDiscoveryError handler → fail-fast (throws)
+      },
+    })
+
+    await expect(
+      collectChunks(stream as AsyncIterable<StreamChunk>),
+    ).rejects.toThrow('discovery failed')
+
+    // goodSource connected and must be closed by cleanup-on-failure
+    expect(goodSource.closed).toBe(true)
+  })
+})
+
+// ============================================================================
+// Structured-output runners + mcp
+//
+// chat() has THREE runners (streaming text, streaming structured output, and
+// non-streaming/agentic structured output). The mcp wiring (discover → merge →
+// dispose) lives in all of them, but the cases above only exercise the
+// streaming-text runner. These pin the structured-output runners so the
+// discovery/merge/close logic can't silently regress there.
+// ============================================================================
+
+describe('chat({ mcp }) — structured-output runners', () => {
+  const OutSchema = z.object({ ok: z.boolean() })
+
+  // A single chatStream turn that finishes without a tool call, so the agent
+  // loop ends and the runner proceeds to structured-output finalization.
+  const finishTurn = () => [
+    ev.runStarted(),
+    ev.textStart(),
+    ev.textContent('{"ok":true}'),
+    ev.textEnd(),
+    ev.runFinished('stop'),
+  ]
+
+  it('streaming structured output (stream:true) discovers MCP tools and closes the source on drain', async () => {
+    const source = fakeSource(['mcpTool'])
+    const { adapter } = createMockAdapter({
+      iterations: [finishTurn()],
+      structuredOutput: async () => ({
+        data: { ok: true },
+        rawText: '{"ok":true}',
+      }),
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'extract' }],
+      outputSchema: OutSchema,
+      stream: true,
+      mcp: { clients: [source] },
+    })
+
+    await collectChunks(stream)
+
+    expect(source.toolCallCount).toBe(1) // discovery ran in this runner
+    expect(source.closed).toBe(true) // dispose ran in this runner
+  })
+
+  it('streaming structured output with keep-alive does NOT close the source', async () => {
+    const source = fakeSource(['mcpTool'])
+    const { adapter } = createMockAdapter({
+      iterations: [finishTurn()],
+      structuredOutput: async () => ({
+        data: { ok: true },
+        rawText: '{"ok":true}',
+      }),
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'extract' }],
+      outputSchema: OutSchema,
+      stream: true,
+      mcp: { clients: [source], connection: 'keep-alive' },
+    })
+
+    await collectChunks(stream)
+
+    expect(source.closed).toBe(false)
+  })
+
+  it('non-streaming structured output (Promise) discovers MCP tools and closes the source', async () => {
+    const source = fakeSource(['mcpTool'])
+    const { adapter } = createMockAdapter({
+      iterations: [finishTurn()],
+      structuredOutput: async () => ({
+        data: { ok: true },
+        rawText: '{"ok":true}',
+      }),
+    })
+
+    const result = await chat({
+      adapter,
+      messages: [{ role: 'user', content: 'extract' }],
+      outputSchema: OutSchema,
+      mcp: { clients: [source] },
+    })
+
+    expect(result).toEqual({ ok: true })
+    expect(source.toolCallCount).toBe(1)
+    expect(source.closed).toBe(true)
+  })
+
+  it('discovered MCP tool executes inside the structured-output agent loop', async () => {
+    const mcpExecuteSpy = vi.fn().mockReturnValue({ mcp: true })
+    const source: MCPToolSource = {
+      tools: async () => [
+        {
+          __toolSide: 'server' as const,
+          name: 'mcpDo',
+          description: 'does a thing via MCP',
+          execute: mcpExecuteSpy,
+        } satisfies ServerTool,
+      ],
+      close: async () => {},
+    }
+
+    const { adapter } = createMockAdapter({
+      iterations: [
+        // Turn 1: the model calls the MCP-discovered tool.
+        [
+          ev.runStarted(),
+          ev.toolStart('call_mcp', 'mcpDo'),
+          ev.toolArgs('call_mcp', '{}'),
+          ev.runFinished('tool_calls'),
+        ],
+        // Turn 2: the model finishes; finalization produces the structured output.
+        finishTurn(),
+      ],
+      structuredOutput: async () => ({
+        data: { ok: true },
+        rawText: '{"ok":true}',
+      }),
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'do it then summarize' }],
+      outputSchema: OutSchema,
+      stream: true,
+      mcp: { clients: [source] },
+    })
+
+    await collectChunks(stream)
+
+    expect(mcpExecuteSpy).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/packages/ai/tests/middleware.test.ts b/packages/ai/tests/middleware.test.ts
index 03b792f12..68af73f16 100644
--- a/packages/ai/tests/middleware.test.ts
+++ b/packages/ai/tests/middleware.test.ts
@@ -1068,6 +1068,66 @@ describe('chat() middleware', () => {
       expect(onAbort.mock.calls[0]![1].reason).toBe('seen enough')
       expect(onFinish).not.toHaveBeenCalled()
     })
+
+    it('propagates ctx.abort() into a running tool via ctx.abortSignal', async () => {
+      let seenSignal: AbortSignal | undefined
+
+      // Tool resolves only when its abort signal fires — without middleware
+      // abort propagation this would hang and the test would time out.
+      const tool = {
+        name: 'slowTool',
+        description: 'waits for abort',
+        execute: (_args: unknown, toolCtx?: { abortSignal?: AbortSignal }) =>
+          new Promise((resolve) => {
+            seenSignal = toolCtx?.abortSignal
+            if (!toolCtx?.abortSignal) {
+              resolve({ done: 'no-signal' })
+              return
+            }
+            if (toolCtx.abortSignal.aborted) {
+              resolve({ done: 'aborted' })
+              return
+            }
+            toolCtx.abortSignal.addEventListener(
+              'abort',
+              () => resolve({ done: 'aborted' }),
+              { once: true },
+            )
+          }),
+      }
+
+      const { adapter } = createMockAdapter({
+        iterations: [
+          [
+            ev.runStarted(),
+            ev.toolStart('tc-1', 'slowTool'),
+            ev.toolArgs('tc-1', '{}'),
+            ev.toolEnd('tc-1', 'slowTool', { input: {} }),
+            ev.runFinished('tool_calls'),
+          ],
+        ],
+      })
+
+      const middleware: ChatMiddleware = {
+        name: 'tool-aborter',
+        onBeforeToolCall: (ctx) => {
+          // Abort shortly after the tool has started executing.
+          setTimeout(() => ctx.abort('mid-tool abort'), 10)
+          return undefined
+        },
+      }
+
+      const stream = chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Hi' }],
+        tools: [tool],
+        middleware: [middleware],
+      })
+      await collectChunks(stream as AsyncIterable<StreamChunk>)
+
+      expect(seenSignal).toBeDefined()
+      expect(seenSignal!.aborted).toBe(true)
+    })
   })
 
   // ==========================================================================
diff --git a/packages/ai/tests/tool-abort-threading.test.ts b/packages/ai/tests/tool-abort-threading.test.ts
new file mode 100644
index 000000000..f054e98b9
--- /dev/null
+++ b/packages/ai/tests/tool-abort-threading.test.ts
@@ -0,0 +1,42 @@
+// packages/ai/tests/tool-abort-threading.test.ts
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { executeToolCalls } from '../src/activities/chat/tools/tool-calls'
+import { toolDefinition } from '../src'
+
+describe('executeToolCalls abort threading', () => {
+  it('forwards an AbortSignal to server tool execute via context', async () => {
+    const controller = new AbortController()
+    let seen: AbortSignal | undefined
+    const tool = toolDefinition({
+      name: 'probe',
+      description: 'probe tool',
+      inputSchema: z.object({}),
+    }).server((_args, ctx) => {
+      seen = ctx?.abortSignal
+      return 'ok'
+    })
+    const calls = [
+      {
+        id: 'c1',
+        type: 'function',
+        function: { name: 'probe', arguments: '{}' },
+      },
+    ]
+    const gen = executeToolCalls(
+      calls as any,
+      [tool],
+      new Map(),
+      new Map(),
+      undefined,
+      undefined,
+      undefined,
+      controller.signal, // new trailing param
+    )
+    // drain
+    while (!(await gen.next()).done) {
+      /* consume events */
+    }
+    expect(seen).toBe(controller.signal)
+  })
+})
diff --git a/packages/ai/tests/tool-execution-context.test.ts b/packages/ai/tests/tool-execution-context.test.ts
new file mode 100644
index 000000000..65b35a6ec
--- /dev/null
+++ b/packages/ai/tests/tool-execution-context.test.ts
@@ -0,0 +1,29 @@
+// packages/ai/tests/tool-execution-context.test.ts
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { toolDefinition } from '../src'
+
+describe('ToolExecutionContext.abortSignal', () => {
+  it('passes the abort signal into a server tool execute', async () => {
+    const controller = new AbortController()
+    let seen: AbortSignal | undefined
+    const tool = toolDefinition({
+      name: 'echo',
+      description: 'Echo a value',
+      inputSchema: z.object({ v: z.string() }),
+    }).server((args, ctx) => {
+      seen = ctx?.abortSignal
+      return args.v
+    })
+    // Invoke execute directly with a context to assert the field is typed + forwarded.
+    await tool.execute!(
+      { v: 'hi' },
+      {
+        toolCallId: 't1',
+        emitCustomEvent: () => {},
+        abortSignal: controller.signal,
+      },
+    )
+    expect(seen).toBe(controller.signal)
+  })
+})
diff --git a/packages/openai-base/src/utils/schema-converter.ts b/packages/openai-base/src/utils/schema-converter.ts
index 9b63f7471..c78174db9 100644
--- a/packages/openai-base/src/utils/schema-converter.ts
+++ b/packages/openai-base/src/utils/schema-converter.ts
@@ -1,9 +1,57 @@
+/**
+ * String `format` values accepted by OpenAI's strict Structured Outputs subset.
+ * Any other format (e.g. "uri", "uri-reference", "regex") causes the API to
+ * reject the whole request with `400 ... '<format>' is not a valid format`.
+ * MCP servers and hand-written tools routinely declare such formats, so we strip
+ * the unsupported ones before sending. See:
+ * https://platform.openai.com/docs/guides/structured-outputs#supported-properties
+ */
+const SUPPORTED_STRING_FORMATS = new Set([
+  'date-time',
+  'time',
+  'date',
+  'duration',
+  'email',
+  'hostname',
+  'ipv4',
+  'ipv6',
+  'uuid',
+])
+
+/**
+ * Recursively drop JSON-Schema `format` keywords whose value isn't in OpenAI's
+ * strict-mode allowlist. Pure — returns a fresh tree and never mutates `node`,
+ * so the caller's original tool definition is left intact.
+ *
+ * A property *named* `format` always has a schema (object/boolean) value, never
+ * a bare string, so it is preserved and recursed into; only the `format`
+ * *keyword* (whose value is a string) is subject to removal.
+ */
+function stripUnsupportedFormats(node: any): any {
+  if (Array.isArray(node)) return node.map(stripUnsupportedFormats)
+  if (node === null || typeof node !== 'object') return node
+
+  const out: Record<string, any> = {}
+  for (const [key, value] of Object.entries(node)) {
+    if (
+      key === 'format' &&
+      typeof value === 'string' &&
+      !SUPPORTED_STRING_FORMATS.has(value)
+    ) {
+      continue
+    }
+    out[key] = stripUnsupportedFormats(value)
+  }
+  return out
+}
+
 /**
  * Transform a JSON schema to be compatible with OpenAI's structured output requirements.
  * OpenAI requires:
  * - All properties must be in the `required` array
  * - Optional fields should have null added to their type union
  * - additionalProperties must be false for objects
+ * - String `format` keywords must be from a fixed allowlist (others are stripped)
  *
  * @param schema - JSON schema to transform
  * @param originalRequired - Original required array (to know which fields were optional)
@@ -12,6 +60,18 @@
 export function makeStructuredOutputCompatible(
   schema: Record<string, any>,
   originalRequired?: Array<string>,
+): Record<string, any> {
+  return stripUnsupportedFormats(coerceStrictSchema(schema, originalRequired))
+}
+
+/**
+ * Strict-mode structural rewrite (required widening, nullability,
+ * additionalProperties). Kept private so the public entry point can apply the
+ * format-stripping pass exactly once over the fully-rewritten tree.
+ */
+function coerceStrictSchema(
+  schema: Record<string, any>,
+  originalRequired?: Array<string>,
 ): Record<string, any> {
   const result = { ...schema }
   const required =
@@ -28,17 +88,14 @@ export function makeStructuredOutputCompatible(
 
       // Step 1: Recurse into nested structures
       if (prop.type === 'object' && prop.properties) {
-        prop = makeStructuredOutputCompatible(prop, prop.required || [])
+        prop = coerceStrictSchema(prop, prop.required || [])
       } else if (prop.type === 'array' && prop.items) {
         prop = {
           ...prop,
-          items: makeStructuredOutputCompatible(
-            prop.items,
-            prop.items.required || [],
-          ),
+          items: coerceStrictSchema(prop.items, prop.items.required || []),
         }
       } else if (prop.anyOf) {
-        prop = makeStructuredOutputCompatible(prop, prop.required || [])
+        prop = coerceStrictSchema(prop, prop.required || [])
       } else if (prop.oneOf) {
         throw new Error(
           'oneOf is not supported in OpenAI structured output schemas. Check the supported outputs here: https://platform.openai.com/docs/guides/structured-outputs#supported-types',
@@ -68,15 +125,12 @@ export function makeStructuredOutputCompatible(
   }
 
   if (result.type === 'array' && result.items) {
-    result.items = makeStructuredOutputCompatible(
-      result.items,
-      result.items.required || [],
-    )
+    result.items = coerceStrictSchema(result.items, result.items.required || [])
   }
 
   if (result.anyOf && Array.isArray(result.anyOf)) {
     result.anyOf = result.anyOf.map((variant) =>
-      makeStructuredOutputCompatible(variant, variant.required || []),
+      coerceStrictSchema(variant, variant.required || []),
     )
   }
 
diff --git a/packages/openai-base/tests/schema-converter.test.ts b/packages/openai-base/tests/schema-converter.test.ts
index d7161a3a9..c19127368 100644
--- a/packages/openai-base/tests/schema-converter.test.ts
+++ b/packages/openai-base/tests/schema-converter.test.ts
@@ -245,4 +245,92 @@ describe('makeStructuredOutputCompatible', () => {
     expect(result.properties.value.anyOf).toContainEqual({ type: 'null' })
     expect(result.properties.value.anyOf).toHaveLength(3)
   })
+
+  it('should strip unsupported string formats (e.g. uri) anywhere in the tree', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        data: { type: 'string', format: 'uri' },
+        nested: {
+          type: 'object',
+          properties: {
+            link: { type: 'string', format: 'uri-reference' },
+          },
+          required: ['link'],
+        },
+        list: {
+          type: 'array',
+          items: { type: 'string', format: 'iri' },
+        },
+      },
+      required: ['data', 'nested', 'list'],
+    }
+
+    const result: any = makeStructuredOutputCompatible(schema, [
+      'data',
+      'nested',
+      'list',
+    ])
+
+    expect(result.properties.data.format).toBeUndefined()
+    expect(result.properties.data.type).toBe('string')
+    expect(result.properties.nested.properties.link.format).toBeUndefined()
+    expect(result.properties.list.items.format).toBeUndefined()
+  })
+
+  it('should retain supported string formats', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        when: { type: 'string', format: 'date-time' },
+        who: { type: 'string', format: 'email' },
+        id: { type: 'string', format: 'uuid' },
+      },
+      required: ['when', 'who', 'id'],
+    }
+
+    const result: any = makeStructuredOutputCompatible(schema, [
+      'when',
+      'who',
+      'id',
+    ])
+
+    expect(result.properties.when.format).toBe('date-time')
+    expect(result.properties.who.format).toBe('email')
+    expect(result.properties.id.format).toBe('uuid')
+  })
+
+  it('should preserve a property literally named "format"', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        // "format" here is a property NAME, not the format keyword — its value
+        // is a schema object and must survive (only its inner unsupported
+        // format keyword is stripped).
+        format: { type: 'string', format: 'uri' },
+      },
+      required: ['format'],
+    }
+
+    const result: any = makeStructuredOutputCompatible(schema, ['format'])
+
+    expect(result.properties.format).toBeDefined()
+    expect(result.properties.format.type).toBe('string')
+    expect(result.properties.format.format).toBeUndefined()
+  })
+
+  it('should not mutate the input schema when stripping formats', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        data: { type: 'string', format: 'uri' },
+      },
+      required: ['data'],
+    }
+
+    makeStructuredOutputCompatible(schema, ['data'])
+
+    // Original definition is untouched — the strip pass returns a fresh tree.
+    expect(schema.properties.data.format).toBe('uri')
+  })
 })
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 01a7a1db0..ab84c8703 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -358,6 +358,9 @@ importers:
       '@tanstack/ai-groq':
         specifier: workspace:*
         version: link:../../packages/ai-groq
+      '@tanstack/ai-mcp':
+        specifier: workspace:*
+        version: link:../../packages/ai-mcp
       '@tanstack/ai-ollama':
         specifier: workspace:*
         version: link:../../packages/ai-ollama
@@ -1245,7 +1248,7 @@ importers:
     dependencies:
       '@google/genai':
         specifier: ^1.43.0
-        version: 1.43.0
+        version: 1.43.0(@modelcontextprotocol/sdk@1.29.0(zod@4.3.6))
       '@tanstack/ai-utils':
         specifier: workspace:*
         version: link:../ai-utils
@@ -1358,6 +1361,34 @@ importers:
         specifier: 4.0.14
         version: 4.0.14(vitest@4.0.14(@opentelemetry/api@1.9.1)(@types/node@24.10.3)(happy-dom@20.0.11)(jiti@2.6.1)(jsdom@27.3.0(postcss@8.5.15))(lightningcss@1.30.2)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
 
+  packages/ai-mcp:
+    dependencies:
+      '@modelcontextprotocol/sdk':
+        specifier: ^1.29.0
+        version: 1.29.0(zod@4.3.6)
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+    devDependencies:
+      '@vitest/coverage-v8':
+        specifier: 4.0.14
+        version: 4.0.14(vitest@4.0.14(@opentelemetry/api@1.9.1)(@types/node@24.10.3)(happy-dom@20.0.11)(jiti@2.6.1)(jsdom@27.3.0(postcss@8.5.15))(lightningcss@1.30.2)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+      jiti:
+        specifier: ^2.4.2
+        version: 2.6.1
+      json-schema-to-typescript:
+        specifier: ^15.0.4
+        version: 15.0.4
+      tsup:
+        specifier: ^8.5.1
+        version: 8.5.1(@microsoft/api-extractor@7.47.7(@types/node@24.10.3))(jiti@2.6.1)(postcss@8.5.15)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
+      vite:
+        specifier: ^7.3.3
+        version: 7.3.3(@types/node@24.10.3)(jiti@2.6.1)(lightningcss@1.30.2)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
+      zod:
+        specifier: ^4.2.0
+        version: 4.3.6
+
   packages/ai-ollama:
     dependencies:
       '@tanstack/ai-utils':
@@ -1807,6 +1838,9 @@ importers:
       '@copilotkit/aimock':
         specifier: ^1.28.1
         version: 1.29.0(vitest@4.1.4(@opentelemetry/api@1.9.1)(@types/node@24.10.3)(happy-dom@20.0.11)(jsdom@27.3.0(postcss@8.5.15))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(lightningcss@1.30.2)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))
+      '@modelcontextprotocol/sdk':
+        specifier: ^1.29.0
+        version: 1.29.0(zod@4.3.6)
       '@openrouter/sdk':
         specifier: 0.12.35
         version: 0.12.35
@@ -1837,6 +1871,9 @@ importers:
       '@tanstack/ai-groq':
         specifier: workspace:*
         version: link:../../packages/ai-groq
+      '@tanstack/ai-mcp':
+        specifier: workspace:*
+        version: link:../../packages/ai-mcp
       '@tanstack/ai-ollama':
         specifier: workspace:*
         version: link:../../packages/ai-ollama
@@ -2089,6 +2126,10 @@ packages:
       zod:
         optional: true
 
+  '@apidevtools/json-schema-ref-parser@11.9.3':
+    resolution: {integrity: sha512-60vepv88RwcJtSHrD6MjIL6Ta3SOYbgfnkHb+ppAVK+o9mXprRtulx7VlRl3lN3bbvysAfCS7WMVfhUYemB0IQ==}
+    engines: {node: '>= 16'}
+
   '@ark/schema@0.56.0':
     resolution: {integrity: sha512-ECg3hox/6Z/nLajxXqNhgPtNdHWC9zNsDyskwO28WinoFEnWow4IsERNz9AnXRhTZJnYIlAJ4uGn3nlLk65vZA==}
 
@@ -4128,6 +4169,9 @@ packages:
   '@jridgewell/trace-mapping@0.3.9':
     resolution: {integrity: sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==}
 
+  '@jsdevtools/ono@7.1.3':
+    resolution: {integrity: sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==}
+
   '@livekit/mutex@1.1.1':
     resolution: {integrity: sha512-EsshAucklmpuUAfkABPxJNhzj9v2sG7JuzFDL4ML1oJQSV14sqrpTYnsaOudMAw9yOaW53NU3QQTlUQoRs4czw==}
 
@@ -4158,6 +4202,16 @@ packages:
   '@microsoft/tsdoc@0.15.1':
     resolution: {integrity: sha512-4aErSrCR/On/e5G2hDP0wjooqDdauzEbIq8hIkIe5pXV0rtWJZvdCEKL0ykZxex+IxIwBp0eGeV48hQN07dXtw==}
 
+  '@modelcontextprotocol/sdk@1.29.0':
+    resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@cfworker/json-schema': ^4.1.1
+      zod: ^3.25 || ^4.0
+    peerDependenciesMeta:
+      '@cfworker/json-schema':
+        optional: true
+
   '@msgpack/msgpack@3.1.3':
     resolution: {integrity: sha512-47XIizs9XZXvuJgoaJUIE2lFoID8ugvc0jzSHP+Ptfk8nTbnR8g788wv48N03Kx0UkAv559HWRQ3yzOgzlRNUA==}
     engines: {node: '>= 18'}
@@ -7172,6 +7226,9 @@ packages:
   '@types/json-schema@7.0.15':
     resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
 
+  '@types/lodash@4.17.24':
+    resolution: {integrity: sha512-gIW7lQLZbue7lRSWEFql49QJJWThrTFFeIMJdp3eH4tKoxm1OvEPg02rm4wCCSHS0cL3/Fizimb35b7k8atwsQ==}
+
   '@types/mdast@4.0.4':
     resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==}
 
@@ -7711,6 +7768,9 @@ packages:
   ajv@8.13.0:
     resolution: {integrity: sha512-PRA911Blj99jR5RMeTunVbNXMF6Lp4vZXnk5GQjcnUWUTsrXtekg/pnmFFI2u/I36Y/2bITGS30GZCXei6uNkA==}
 
+  ajv@8.20.0:
+    resolution: {integrity: sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==}
+
   alien-signals@1.0.13:
     resolution: {integrity: sha512-OGj9yyTnJEttvzhTUWuscOvtqxq5vrhF7vL9oS0xJ2mK0ItPYP1/y+vCFebfxoEyAz0++1AIwJ5CMr+Fk3nDmg==}
 
@@ -8415,6 +8475,10 @@ packages:
   core-util-is@1.0.3:
     resolution: {integrity: sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==}
 
+  cors@2.8.6:
+    resolution: {integrity: sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==}
+    engines: {node: '>= 0.10'}
+
   cosmiconfig@9.0.1:
     resolution: {integrity: sha512-hr4ihw+DBqcvrsEDioRO31Z17x71pUYoNe/4h6Z0wB72p7MU7/9gH8Q3s12NFhHPfYBBOV3qyfUxmr/Yn3shnQ==}
     engines: {node: '>=14'}
@@ -9088,6 +9152,14 @@ packages:
     resolution: {integrity: sha512-v0eOBUbiaFojBu2s2NPBfYUoRR9GjcDNvCXVaqEf5vVfpIAh9f8RCo4vXTP8c63QRKCFwoLpMpTdPwwhEKVgzA==}
     engines: {node: '>=14.18'}
 
+  eventsource-parser@3.1.0:
+    resolution: {integrity: sha512-kJezFj9YFAMLeORyi7aCLxLbD5/qWMQnoMVlVPyHIll7lgRJCc3JVln9Vgl9nwQi0YkMnhdGTMNn7CkRRAptMg==}
+    engines: {node: '>=18.0.0'}
+
+  eventsource@3.0.7:
+    resolution: {integrity: sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==}
+    engines: {node: '>=18.0.0'}
+
   execa@8.0.1:
     resolution: {integrity: sha512-VyhnebXciFV2DESc+p6B+y0LjSm0krU4OgJN44qFAhBY0TJ+1V61tYD2+wHusZ6F9n5K+vl8k0sTy7PEfV4qpg==}
     engines: {node: '>=16.17'}
@@ -9177,6 +9249,12 @@ packages:
   exponential-backoff@3.1.3:
     resolution: {integrity: sha512-ZgEeZXj30q+I0EN+CbSSpIyPaJ5HVQD18Z1m+u1FXbAeT94mr1zw50q4q6jiiC447Nl/YTcIYSAftiGqetwXCA==}
 
+  express-rate-limit@8.5.2:
+    resolution: {integrity: sha512-5Kb34ipNX694DH48vN9irak1Qx30nb0PLYHXfJgw4YEjiC3ZEmZJhwOp+VfiCYwFzvFTdB9QkArYS5kXa2cx2A==}
+    engines: {node: '>= 16'}
+    peerDependencies:
+      express: '>= 4.11'
+
   express@5.2.1:
     resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
     engines: {node: '>= 18'}
@@ -9218,6 +9296,9 @@ packages:
   fast-sha256@1.3.0:
     resolution: {integrity: sha512-n11RGP/lrWEFI/bWdygLxhI+pVeo1ZYIVwvvPkW7azl/rOy+F3HYRZ2K5zeE9mmkhQppyv9sQFx0JM9UabnpPQ==}
 
+  fast-uri@3.1.2:
+    resolution: {integrity: sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==}
+
   fastq@1.19.1:
     resolution: {integrity: sha512-GwLTyxkCXjXbxqIhTsMI2Nui8huMPtnxg7krajPJAjnEG/iiOS7i+zCtWGZR9G0NBKbXKh6X9m9UIsYX/N6vvQ==}
 
@@ -9815,6 +9896,10 @@ packages:
     resolution: {integrity: sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==}
     engines: {node: '>= 12'}
 
+  ip-address@10.2.0:
+    resolution: {integrity: sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==}
+    engines: {node: '>= 12'}
+
   ipaddr.js@1.9.1:
     resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
     engines: {node: '>= 0.10'}
@@ -10162,12 +10247,20 @@ packages:
     resolution: {integrity: sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==}
     engines: {node: '>=16'}
 
+  json-schema-to-typescript@15.0.4:
+    resolution: {integrity: sha512-Su9oK8DR4xCmDsLlyvadkXzX6+GGXJpbhwoLtOGArAG61dvbW4YQmSEno2y66ahpIdmLMg6YUf/QHLgiwvkrHQ==}
+    engines: {node: '>=16.0.0'}
+    hasBin: true
+
   json-schema-traverse@0.4.1:
     resolution: {integrity: sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==}
 
   json-schema-traverse@1.0.0:
     resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
 
+  json-schema-typed@8.0.2:
+    resolution: {integrity: sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==}
+
   json-stable-stringify-without-jsonify@1.0.1:
     resolution: {integrity: sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==}
 
@@ -11383,6 +11476,10 @@ packages:
     resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==}
     engines: {node: '>= 6'}
 
+  pkce-challenge@5.0.1:
+    resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
+    engines: {node: '>=16.20.0'}
+
   pkg-dir@3.0.0:
     resolution: {integrity: sha512-/E57AYkoeQ25qkxMj5PBOVgF8Kiu/h7cYS30Z5+R7WaiCCBfLq58ZI/dSeaEKb9WVJV5n/03QwrN3IeWIFllvw==}
     engines: {node: '>=6'}
@@ -13774,6 +13871,11 @@ packages:
     resolution: {integrity: sha512-zK7YHHz4ZXpW89AHXUPbQVGKI7uvkd3hzusTdotCg1UxyaVtg0zFJSTfW/Dq5f7OBBVnq6cZIaC8Ti4hb6dtCA==}
     engines: {node: '>= 14'}
 
+  zod-to-json-schema@3.25.2:
+    resolution: {integrity: sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==}
+    peerDependencies:
+      zod: ^3.25.28 || ^4
+
   zod@3.25.76:
     resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
 
@@ -13801,6 +13903,12 @@ snapshots:
     optionalDependencies:
       zod: 4.2.1
 
+  '@apidevtools/json-schema-ref-parser@11.9.3':
+    dependencies:
+      '@jsdevtools/ono': 7.1.3
+      '@types/json-schema': 7.0.15
+      js-yaml: 4.1.1
+
   '@ark/schema@0.56.0':
     dependencies:
       '@ark/util': 0.56.0
@@ -15638,12 +15746,14 @@ snapshots:
       '@shikijs/types': 3.20.0
       '@shikijs/vscode-textmate': 10.0.2
 
-  '@google/genai@1.43.0':
+  '@google/genai@1.43.0(@modelcontextprotocol/sdk@1.29.0(zod@4.3.6))':
     dependencies:
       google-auth-library: 10.5.0
       p-retry: 4.6.2
       protobufjs: 7.5.4
       ws: 8.18.3
+    optionalDependencies:
+      '@modelcontextprotocol/sdk': 1.29.0(zod@4.3.6)
     transitivePeerDependencies:
       - bufferutil
       - supports-color
@@ -15872,6 +15982,8 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  '@jsdevtools/ono@7.1.3': {}
+
   '@livekit/mutex@1.1.1': {}
 
   '@livekit/protocol@1.44.0':
@@ -15942,6 +16054,28 @@ snapshots:
 
   '@microsoft/tsdoc@0.15.1': {}
 
+  '@modelcontextprotocol/sdk@1.29.0(zod@4.3.6)':
+    dependencies:
+      '@hono/node-server': 1.19.14(hono@4.12.23)
+      ajv: 8.20.0
+      ajv-formats: 3.0.1(ajv@8.20.0)
+      content-type: 1.0.5
+      cors: 2.8.6
+      cross-spawn: 7.0.6
+      eventsource: 3.0.7
+      eventsource-parser: 3.1.0
+      express: 5.2.1
+      express-rate-limit: 8.5.2(express@5.2.1)
+      hono: 4.12.23
+      jose: 6.2.0
+      json-schema-typed: 8.0.2
+      pkce-challenge: 5.0.1
+      raw-body: 3.0.2
+      zod: 4.3.6
+      zod-to-json-schema: 3.25.2(zod@4.3.6)
+    transitivePeerDependencies:
+      - supports-color
+
   '@msgpack/msgpack@3.1.3': {}
 
   '@msgpackr-extract/msgpackr-extract-darwin-arm64@3.0.4':
@@ -19406,6 +19540,8 @@ snapshots:
 
   '@types/json-schema@7.0.15': {}
 
+  '@types/lodash@4.17.24': {}
+
   '@types/mdast@4.0.4':
     dependencies:
       '@types/unist': 3.0.3
@@ -20070,6 +20206,10 @@ snapshots:
     optionalDependencies:
       ajv: 8.13.0
 
+  ajv-formats@3.0.1(ajv@8.20.0):
+    optionalDependencies:
+      ajv: 8.20.0
+
   ajv@6.12.6:
     dependencies:
       fast-deep-equal: 3.1.3
@@ -20098,6 +20238,13 @@ snapshots:
       require-from-string: 2.0.2
       uri-js: 4.4.1
 
+  ajv@8.20.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-uri: 3.1.2
+      json-schema-traverse: 1.0.0
+      require-from-string: 2.0.2
+
   alien-signals@1.0.13: {}
 
   anser@1.4.10: {}
@@ -20891,6 +21038,11 @@ snapshots:
 
   core-util-is@1.0.3: {}
 
+  cors@2.8.6:
+    dependencies:
+      object-assign: 4.1.1
+      vary: 1.1.2
+
   cosmiconfig@9.0.1(typescript@5.9.3):
     dependencies:
       env-paths: 2.2.1
@@ -21671,6 +21823,12 @@ snapshots:
 
   eventsource-parser@1.1.2: {}
 
+  eventsource-parser@3.1.0: {}
+
+  eventsource@3.0.7:
+    dependencies:
+      eventsource-parser: 3.1.0
+
   execa@8.0.1:
     dependencies:
       cross-spawn: 7.0.6
@@ -21787,6 +21945,11 @@ snapshots:
 
   exponential-backoff@3.1.3: {}
 
+  express-rate-limit@8.5.2(express@5.2.1):
+    dependencies:
+      express: 5.2.1
+      ip-address: 10.2.0
+
   express@5.2.1:
     dependencies:
       accepts: 2.0.0
@@ -21856,6 +22019,8 @@ snapshots:
 
   fast-sha256@1.3.0: {}
 
+  fast-uri@3.1.2: {}
+
   fastq@1.19.1:
     dependencies:
       reusify: 1.1.0
@@ -22561,6 +22726,8 @@ snapshots:
 
   ip-address@10.1.0: {}
 
+  ip-address@10.2.0: {}
+
   ipaddr.js@1.9.1: {}
 
   iron-webcrypto@1.2.1: {}
@@ -22910,10 +23077,24 @@ snapshots:
       '@babel/runtime': 7.29.2
       ts-algebra: 2.0.0
 
+  json-schema-to-typescript@15.0.4:
+    dependencies:
+      '@apidevtools/json-schema-ref-parser': 11.9.3
+      '@types/json-schema': 7.0.15
+      '@types/lodash': 4.17.24
+      is-glob: 4.0.3
+      js-yaml: 4.1.1
+      lodash: 4.17.21
+      minimist: 1.2.8
+      prettier: 3.7.4
+      tinyglobby: 0.2.16
+
   json-schema-traverse@0.4.1: {}
 
   json-schema-traverse@1.0.0: {}
 
+  json-schema-typed@8.0.2: {}
+
   json-stable-stringify-without-jsonify@1.0.1: {}
 
   json5@2.2.3: {}
@@ -23194,8 +23375,8 @@ snapshots:
 
   magicast@0.5.2:
     dependencies:
-      '@babel/parser': 7.29.0
-      '@babel/types': 7.29.0
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
       source-map-js: 1.2.1
 
   make-dir@2.1.0:
@@ -24726,6 +24907,8 @@ snapshots:
 
   pirates@4.0.7: {}
 
+  pkce-challenge@5.0.1: {}
+
   pkg-dir@3.0.0:
     dependencies:
       find-up: 3.0.0
@@ -27340,6 +27523,10 @@ snapshots:
       compress-commons: 6.0.2
       readable-stream: 4.7.0
 
+  zod-to-json-schema@3.25.2(zod@4.3.6):
+    dependencies:
+      zod: 4.3.6
+
   zod@3.25.76: {}
 
   zod@4.2.1: {}
diff --git a/testing/e2e/fixtures/mcp/basic.json b/testing/e2e/fixtures/mcp/basic.json
new file mode 100644
index 000000000..8e73db2ed
--- /dev/null
+++ b/testing/e2e/fixtures/mcp/basic.json
@@ -0,0 +1,25 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[mcp] how much is the strat guitar",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "content": "Let me look up the price.",
+        "toolCalls": [
+          { "name": "get_guitar_price", "arguments": "{\"id\":\"strat\"}" }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[mcp] how much is the strat guitar",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "The strat guitar costs $1999."
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/fixtures/mcp/lifecycle.json b/testing/e2e/fixtures/mcp/lifecycle.json
new file mode 100644
index 000000000..e4fa9dd68
--- /dev/null
+++ b/testing/e2e/fixtures/mcp/lifecycle.json
@@ -0,0 +1,13 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[mcp-lifecycle] ping",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "content": "pong"
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/package.json b/testing/e2e/package.json
index f4d096a83..af0e4ad99 100644
--- a/testing/e2e/package.json
+++ b/testing/e2e/package.json
@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@copilotkit/aimock": "^1.28.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@openrouter/sdk": "0.12.35",
     "@opentelemetry/api": "^1.9.0",
     "@tailwindcss/vite": "^4.1.18",
@@ -22,6 +23,7 @@
     "@tanstack/ai-gemini": "workspace:*",
     "@tanstack/ai-grok": "workspace:*",
     "@tanstack/ai-groq": "workspace:*",
+    "@tanstack/ai-mcp": "workspace:*",
     "@tanstack/ai-ollama": "workspace:*",
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-openrouter": "workspace:*",
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index 55db5b744..165f14d4d 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -31,6 +31,11 @@ import { Route as ApiOpenaiUsageDetailsRouteImport } from './routes/api.openai-u
 import { Route as ApiOpenaiShellSkillsWireRouteImport } from './routes/api.openai-shell-skills-wire'
 import { Route as ApiMultimodalToolResultWireRouteImport } from './routes/api.multimodal-tool-result-wire'
 import { Route as ApiMiddlewareTestRouteImport } from './routes/api.middleware-test'
+import { Route as ApiMcpTestRouteImport } from './routes/api.mcp-test'
+import { Route as ApiMcpStatusTestRouteImport } from './routes/api.mcp-status-test'
+import { Route as ApiMcpServerRouteImport } from './routes/api.mcp-server'
+import { Route as ApiMcpManagedTestRouteImport } from './routes/api.mcp-managed-test'
+import { Route as ApiMcpLifecycleTestRouteImport } from './routes/api.mcp-lifecycle-test'
 import { Route as ApiImageRouteImport } from './routes/api.image'
 import { Route as ApiChatRouteImport } from './routes/api.chat'
 import { Route as ApiAudioRouteImport } from './routes/api.audio'
@@ -157,6 +162,31 @@ const ApiMiddlewareTestRoute = ApiMiddlewareTestRouteImport.update({
   path: '/api/middleware-test',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiMcpTestRoute = ApiMcpTestRouteImport.update({
+  id: '/api/mcp-test',
+  path: '/api/mcp-test',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiMcpStatusTestRoute = ApiMcpStatusTestRouteImport.update({
+  id: '/api/mcp-status-test',
+  path: '/api/mcp-status-test',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiMcpServerRoute = ApiMcpServerRouteImport.update({
+  id: '/api/mcp-server',
+  path: '/api/mcp-server',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiMcpManagedTestRoute = ApiMcpManagedTestRouteImport.update({
+  id: '/api/mcp-managed-test',
+  path: '/api/mcp-managed-test',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiMcpLifecycleTestRoute = ApiMcpLifecycleTestRouteImport.update({
+  id: '/api/mcp-lifecycle-test',
+  path: '/api/mcp-lifecycle-test',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiImageRoute = ApiImageRouteImport.update({
   id: '/api/image',
   path: '/api/image',
@@ -236,6 +266,11 @@ export interface FileRoutesByFullPath {
   '/api/audio': typeof ApiAudioRouteWithChildren
   '/api/chat': typeof ApiChatRoute
   '/api/image': typeof ApiImageRouteWithChildren
+  '/api/mcp-lifecycle-test': typeof ApiMcpLifecycleTestRoute
+  '/api/mcp-managed-test': typeof ApiMcpManagedTestRoute
+  '/api/mcp-server': typeof ApiMcpServerRoute
+  '/api/mcp-status-test': typeof ApiMcpStatusTestRoute
+  '/api/mcp-test': typeof ApiMcpTestRoute
   '/api/middleware-test': typeof ApiMiddlewareTestRoute
   '/api/multimodal-tool-result-wire': typeof ApiMultimodalToolResultWireRoute
   '/api/openai-shell-skills-wire': typeof ApiOpenaiShellSkillsWireRoute
@@ -272,6 +307,11 @@ export interface FileRoutesByTo {
   '/api/audio': typeof ApiAudioRouteWithChildren
   '/api/chat': typeof ApiChatRoute
   '/api/image': typeof ApiImageRouteWithChildren
+  '/api/mcp-lifecycle-test': typeof ApiMcpLifecycleTestRoute
+  '/api/mcp-managed-test': typeof ApiMcpManagedTestRoute
+  '/api/mcp-server': typeof ApiMcpServerRoute
+  '/api/mcp-status-test': typeof ApiMcpStatusTestRoute
+  '/api/mcp-test': typeof ApiMcpTestRoute
   '/api/middleware-test': typeof ApiMiddlewareTestRoute
   '/api/multimodal-tool-result-wire': typeof ApiMultimodalToolResultWireRoute
   '/api/openai-shell-skills-wire': typeof ApiOpenaiShellSkillsWireRoute
@@ -309,6 +349,11 @@ export interface FileRoutesById {
   '/api/audio': typeof ApiAudioRouteWithChildren
   '/api/chat': typeof ApiChatRoute
   '/api/image': typeof ApiImageRouteWithChildren
+  '/api/mcp-lifecycle-test': typeof ApiMcpLifecycleTestRoute
+  '/api/mcp-managed-test': typeof ApiMcpManagedTestRoute
+  '/api/mcp-server': typeof ApiMcpServerRoute
+  '/api/mcp-status-test': typeof ApiMcpStatusTestRoute
+  '/api/mcp-test': typeof ApiMcpTestRoute
   '/api/middleware-test': typeof ApiMiddlewareTestRoute
   '/api/multimodal-tool-result-wire': typeof ApiMultimodalToolResultWireRoute
   '/api/openai-shell-skills-wire': typeof ApiOpenaiShellSkillsWireRoute
@@ -347,6 +392,11 @@ export interface FileRouteTypes {
     | '/api/audio'
     | '/api/chat'
     | '/api/image'
+    | '/api/mcp-lifecycle-test'
+    | '/api/mcp-managed-test'
+    | '/api/mcp-server'
+    | '/api/mcp-status-test'
+    | '/api/mcp-test'
     | '/api/middleware-test'
     | '/api/multimodal-tool-result-wire'
     | '/api/openai-shell-skills-wire'
@@ -383,6 +433,11 @@ export interface FileRouteTypes {
     | '/api/audio'
     | '/api/chat'
     | '/api/image'
+    | '/api/mcp-lifecycle-test'
+    | '/api/mcp-managed-test'
+    | '/api/mcp-server'
+    | '/api/mcp-status-test'
+    | '/api/mcp-test'
     | '/api/middleware-test'
     | '/api/multimodal-tool-result-wire'
     | '/api/openai-shell-skills-wire'
@@ -419,6 +474,11 @@ export interface FileRouteTypes {
     | '/api/audio'
     | '/api/chat'
     | '/api/image'
+    | '/api/mcp-lifecycle-test'
+    | '/api/mcp-managed-test'
+    | '/api/mcp-server'
+    | '/api/mcp-status-test'
+    | '/api/mcp-test'
     | '/api/middleware-test'
     | '/api/multimodal-tool-result-wire'
     | '/api/openai-shell-skills-wire'
@@ -456,6 +516,11 @@ export interface RootRouteChildren {
   ApiAudioRoute: typeof ApiAudioRouteWithChildren
   ApiChatRoute: typeof ApiChatRoute
   ApiImageRoute: typeof ApiImageRouteWithChildren
+  ApiMcpLifecycleTestRoute: typeof ApiMcpLifecycleTestRoute
+  ApiMcpManagedTestRoute: typeof ApiMcpManagedTestRoute
+  ApiMcpServerRoute: typeof ApiMcpServerRoute
+  ApiMcpStatusTestRoute: typeof ApiMcpStatusTestRoute
+  ApiMcpTestRoute: typeof ApiMcpTestRoute
   ApiMiddlewareTestRoute: typeof ApiMiddlewareTestRoute
   ApiMultimodalToolResultWireRoute: typeof ApiMultimodalToolResultWireRoute
   ApiOpenaiShellSkillsWireRoute: typeof ApiOpenaiShellSkillsWireRoute
@@ -626,6 +691,41 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiMiddlewareTestRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/mcp-test': {
+      id: '/api/mcp-test'
+      path: '/api/mcp-test'
+      fullPath: '/api/mcp-test'
+      preLoaderRoute: typeof ApiMcpTestRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/mcp-status-test': {
+      id: '/api/mcp-status-test'
+      path: '/api/mcp-status-test'
+      fullPath: '/api/mcp-status-test'
+      preLoaderRoute: typeof ApiMcpStatusTestRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/mcp-server': {
+      id: '/api/mcp-server'
+      path: '/api/mcp-server'
+      fullPath: '/api/mcp-server'
+      preLoaderRoute: typeof ApiMcpServerRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/mcp-managed-test': {
+      id: '/api/mcp-managed-test'
+      path: '/api/mcp-managed-test'
+      fullPath: '/api/mcp-managed-test'
+      preLoaderRoute: typeof ApiMcpManagedTestRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/mcp-lifecycle-test': {
+      id: '/api/mcp-lifecycle-test'
+      path: '/api/mcp-lifecycle-test'
+      fullPath: '/api/mcp-lifecycle-test'
+      preLoaderRoute: typeof ApiMcpLifecycleTestRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/image': {
       id: '/api/image'
       path: '/api/image'
@@ -789,6 +889,11 @@ const rootRouteChildren: RootRouteChildren = {
   ApiAudioRoute: ApiAudioRouteWithChildren,
   ApiChatRoute: ApiChatRoute,
   ApiImageRoute: ApiImageRouteWithChildren,
+  ApiMcpLifecycleTestRoute: ApiMcpLifecycleTestRoute,
+  ApiMcpManagedTestRoute: ApiMcpManagedTestRoute,
+  ApiMcpServerRoute: ApiMcpServerRoute,
+  ApiMcpStatusTestRoute: ApiMcpStatusTestRoute,
+  ApiMcpTestRoute: ApiMcpTestRoute,
   ApiMiddlewareTestRoute: ApiMiddlewareTestRoute,
   ApiMultimodalToolResultWireRoute: ApiMultimodalToolResultWireRoute,
   ApiOpenaiShellSkillsWireRoute: ApiOpenaiShellSkillsWireRoute,
diff --git a/testing/e2e/src/routes/api.mcp-lifecycle-test.ts b/testing/e2e/src/routes/api.mcp-lifecycle-test.ts
new file mode 100644
index 000000000..a047008fe
--- /dev/null
+++ b/testing/e2e/src/routes/api.mcp-lifecycle-test.ts
@@ -0,0 +1,99 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, chatParamsFromRequestBody, maxIterations } from '@tanstack/ai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import type { StreamChunk } from '@tanstack/ai'
+import { createTextAdapter } from '@/lib/providers'
+
+/**
+ * Validates `chat({ mcp: { connection } })` lifecycle semantics end-to-end.
+ *
+ * Runs a real `chat()` agent loop with one MCP client, drains it, then probes
+ * the client AFTER the run:
+ *   - `connection: 'close'` (default) → chat closed the client → `client.tools()`
+ *     now throws → `survivedAfterRun: false`.
+ *   - `connection: 'keep-alive'`      → chat left the client open → `client.tools()`
+ *     still works → `survivedAfterRun: true` (we then close it ourselves).
+ *
+ * Returns JSON so the spec can assert the lifecycle deterministically without
+ * scraping the SSE stream. The aimock fixture (`fixtures/mcp/lifecycle.json`)
+ * returns a plain text turn (no tool call) — the tool isn't needed; only the
+ * client lifecycle is under test.
+ */
+export const Route = createFileRoute('/api/mcp-lifecycle-test')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        let params
+        try {
+          params = await chatParamsFromRequestBody(await request.json())
+        } catch (error) {
+          return new Response(
+            error instanceof Error ? error.message : 'Bad request',
+            { status: 400 },
+          )
+        }
+
+        const fp = params.forwardedProps
+        const testId = typeof fp.testId === 'string' ? fp.testId : undefined
+        const aimockPort =
+          fp.aimockPort != null ? Number(fp.aimockPort) : undefined
+        const connection =
+          fp.connection === 'keep-alive' ? 'keep-alive' : 'close'
+
+        const origin = new URL(request.url).origin
+        const mcpUrl = `${origin}/api/mcp-server`
+
+        try {
+          const client = await createMCPClient({
+            transport: { type: 'http', url: mcpUrl },
+          })
+
+          const adapterOptions = createTextAdapter(
+            'openai',
+            undefined,
+            aimockPort,
+            testId,
+          )
+
+          const stream = chat({
+            ...adapterOptions,
+            messages: params.messages,
+            threadId: params.threadId,
+            runId: params.runId,
+            mcp: { clients: [client], connection },
+            agentLoopStrategy: maxIterations(3),
+          })
+
+          // Drain internally so chat()'s mcp dispose (the `finally`) has run by
+          // the time we probe the client below.
+          for await (const _chunk of stream as AsyncIterable<StreamChunk>) {
+            // discard
+          }
+
+          let survivedAfterRun = false
+          try {
+            await client.tools()
+            survivedAfterRun = true
+          } catch {
+            survivedAfterRun = false
+          }
+
+          // For keep-alive, chat left the connection open — close it now so the
+          // test doesn't leak an MCP connection.
+          if (survivedAfterRun) {
+            await client.close().catch(() => {})
+          }
+
+          return Response.json({ connection, survivedAfterRun })
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : 'An error occurred'
+          return new Response(JSON.stringify({ error: message }), {
+            status: 500,
+            headers: { 'Content-Type': 'application/json' },
+          })
+        }
+      },
+    },
+  },
+})
diff --git a/testing/e2e/src/routes/api.mcp-managed-test.ts b/testing/e2e/src/routes/api.mcp-managed-test.ts
new file mode 100644
index 000000000..459dcc42b
--- /dev/null
+++ b/testing/e2e/src/routes/api.mcp-managed-test.ts
@@ -0,0 +1,96 @@
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  chat,
+  chatParamsFromRequestBody,
+  maxIterations,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { createTextAdapter } from '@/lib/providers'
+
+/**
+ * Drives a real `chat()` agent loop with MCP tool discovery managed entirely
+ * by `chat({ mcp })` — the caller does NOT manually call `mcp.tools()` or
+ * `mcp.close()`. This verifies that passing `mcp: { clients, connection }` to
+ * `chat()` correctly:
+ *   1. Auto-discovers tools from the MCP client (here: `get_guitar_price`).
+ *   2. Runs the tool inside the agent loop via the aimock fixture.
+ *   3. Closes the client after the stream drains (connection: 'close').
+ *
+ * Contrast with `api.mcp-test.ts` which manually calls `mcp.tools()`, wraps
+ * the stream in a `closeMcpOnDrain` generator, and passes `tools` directly.
+ */
+export const Route = createFileRoute('/api/mcp-managed-test')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        if (request.signal.aborted) {
+          return new Response(null, { status: 499 })
+        }
+
+        const abortController = new AbortController()
+
+        let params
+        try {
+          params = await chatParamsFromRequestBody(await request.json())
+        } catch (error) {
+          return new Response(
+            error instanceof Error ? error.message : 'Bad request',
+            { status: 400 },
+          )
+        }
+
+        const fp = params.forwardedProps
+        const testId = typeof fp.testId === 'string' ? fp.testId : undefined
+        const aimockPort =
+          fp.aimockPort != null ? Number(fp.aimockPort) : undefined
+
+        // The mock MCP server lives at this same dev server's origin.
+        const origin = new URL(request.url).origin
+        const mcpServerUrl = `${origin}/api/mcp-server`
+
+        try {
+          // Create the MCP client — but do NOT call client.tools() or
+          // client.close() here. Pass it to chat({ mcp }) and let chat manage
+          // the full lifecycle: discovery, execution, and teardown.
+          const client = await createMCPClient({
+            transport: { type: 'http', url: mcpServerUrl },
+          })
+
+          const adapterOptions = createTextAdapter(
+            'openai',
+            undefined,
+            aimockPort,
+            testId,
+          )
+
+          const stream = chat({
+            ...adapterOptions,
+            messages: params.messages,
+            threadId: params.threadId,
+            runId: params.runId,
+            mcp: { clients: [client], connection: 'close' },
+            agentLoopStrategy: maxIterations(5),
+            abortController,
+          })
+
+          return toServerSentEventsResponse(stream, { abortController })
+        } catch (error) {
+          console.error('[api.mcp-managed-test] Error:', error)
+          if (
+            (error instanceof Error && error.name === 'AbortError') ||
+            abortController.signal.aborted
+          ) {
+            return new Response(null, { status: 499 })
+          }
+          const message =
+            error instanceof Error ? error.message : 'An error occurred'
+          return new Response(JSON.stringify({ error: message }), {
+            status: 500,
+            headers: { 'Content-Type': 'application/json' },
+          })
+        }
+      },
+    },
+  },
+})
diff --git a/testing/e2e/src/routes/api.mcp-server.ts b/testing/e2e/src/routes/api.mcp-server.ts
new file mode 100644
index 000000000..75ffcf1a8
--- /dev/null
+++ b/testing/e2e/src/routes/api.mcp-server.ts
@@ -0,0 +1,126 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js'
+import { z } from 'zod'
+
+/**
+ * In-process mock MCP server hosted as a TanStack Start API route.
+ *
+ * This is a *real* MCP server (via `@modelcontextprotocol/sdk`'s `McpServer`)
+ * speaking the Streamable HTTP protocol over Web Standard Request/Response.
+ * The companion `api.mcp-test` route connects to it at this same dev-server
+ * origin via `@tanstack/ai-mcp`'s `createMCPClient({ transport: { type:
+ * 'http', url } })`, discovers its tools, and runs them inside a real `chat()`
+ * agent loop (with the LLM mocked by aimock).
+ *
+ * Stateless mode (no `sessionIdGenerator`): a fresh `McpServer` + transport is
+ * created per request. This avoids any cross-request session bookkeeping —
+ * appropriate for a serverless-style route and for deterministic tests. The
+ * transport is closed once the response has been produced.
+ *
+ * The single tool `get_guitar_price` is fully deterministic: given `{ id }` it
+ * returns both a structured payload and a text block carrying `{ id, price:
+ * 1999 }`, so the spec can assert the price `1999` reaches the streamed
+ * transcript after the tool executes.
+ */
+function createMockMcpServer(): McpServer {
+  const server = new McpServer({
+    name: 'guitar-store-mcp-mock',
+    version: '0.0.1',
+  })
+
+  server.registerTool(
+    'get_guitar_price',
+    {
+      description: 'Get the price of a guitar by its id',
+      inputSchema: { id: z.string() },
+      outputSchema: { id: z.string(), price: z.number() },
+    },
+    ({ id }) => {
+      const payload = { id, price: 1999 }
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(payload) }],
+        structuredContent: payload,
+      }
+    },
+  )
+
+  // A task-required tool (experimental MCP tasks). Plain `callTool` would be
+  // rejected with -32600, so @tanstack/ai-mcp must EXCLUDE it from tools()
+  // discovery — the spec asserts it never reaches the tool list.
+  const taskTool = server.registerTool(
+    'appraise_guitar_collection',
+    {
+      description: 'Long-running appraisal that requires task-based execution',
+      inputSchema: { ids: z.array(z.string()) },
+    },
+    () => ({
+      content: [{ type: 'text' as const, text: 'unreachable via callTool' }],
+    }),
+  )
+  // registerTool's config doesn't accept `execution` directly in SDK 1.29;
+  // RegisteredTool exposes it as a mutable property consumed at list time.
+  taskTool.execution = { taskSupport: 'required' }
+
+  // A static resource + prompt so the resource/prompt read+convert path can be
+  // exercised end-to-end (see api.mcp-status-test). The catalog text carries a
+  // distinctive token (STRAT-001) the spec asserts survives conversion.
+  server.registerResource(
+    'catalog',
+    'guitar://catalog',
+    { description: 'Featured guitar catalog', mimeType: 'text/plain' },
+    async () => ({
+      contents: [
+        {
+          uri: 'guitar://catalog',
+          text: 'Featured guitar: Fender Stratocaster (SKU STRAT-001), price 1999.',
+        },
+      ],
+    }),
+  )
+
+  server.registerPrompt(
+    'recommend_guitar',
+    { description: 'Ask for a beginner-friendly guitar recommendation' },
+    () => ({
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: 'Recommend a beginner-friendly electric guitar under $500.',
+          },
+        },
+      ],
+    }),
+  )
+
+  return server
+}
+
+async function handleMcpRequest(request: Request): Promise<Response> {
+  const server = createMockMcpServer()
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    // Stateless mode — no session id is generated or validated. A fresh
+    // server+transport pair handles this single request and is then GC'd.
+    sessionIdGenerator: undefined,
+  })
+
+  // The McpServer assumes ownership of the transport and tears down its own
+  // per-request streams when the response stream completes; in stateless mode
+  // we deliberately do NOT close the transport here, since doing so before the
+  // SSE body drains would abort the in-flight response.
+  await server.connect(transport)
+
+  return transport.handleRequest(request)
+}
+
+export const Route = createFileRoute('/api/mcp-server')({
+  server: {
+    handlers: {
+      POST: ({ request }) => handleMcpRequest(request),
+      GET: ({ request }) => handleMcpRequest(request),
+      DELETE: ({ request }) => handleMcpRequest(request),
+    },
+  },
+})
diff --git a/testing/e2e/src/routes/api.mcp-status-test.ts b/testing/e2e/src/routes/api.mcp-status-test.ts
new file mode 100644
index 000000000..40d1d2a95
--- /dev/null
+++ b/testing/e2e/src/routes/api.mcp-status-test.ts
@@ -0,0 +1,61 @@
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  createMCPClient,
+  mcpPromptToMessages,
+  mcpResourceToContentPart,
+} from '@tanstack/ai-mcp'
+
+/**
+ * Capability-probe endpoint for the in-process MCP server (`api.mcp-server`).
+ *
+ * Connects via `@tanstack/ai-mcp`, then lists + reads the server's tools,
+ * resources, and prompts — converting resources/prompts through the public
+ * `mcpResourceToContentPart` / `mcpPromptToMessages` helpers. Returns the
+ * result as JSON so a spec can validate the resource/prompt read+convert path
+ * end-to-end against a real Streamable-HTTP MCP server, with no LLM involved.
+ *
+ * No aimock dependency: this exercises only the MCP client surface.
+ */
+export const Route = createFileRoute('/api/mcp-status-test')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const origin = new URL(request.url).origin
+        const mcpUrl = `${origin}/api/mcp-server`
+
+        const client = await createMCPClient({
+          transport: { type: 'http', url: mcpUrl },
+        })
+        try {
+          const tools = (await client.tools()).map((t) => t.name)
+
+          const resourceList = await client.resources().catch(() => [])
+          const resourceContent: Array<unknown> = []
+          for (const r of resourceList) {
+            const read = await client.readResource(r.uri)
+            for (const c of read.contents) {
+              resourceContent.push(mcpResourceToContentPart(c))
+            }
+          }
+
+          const promptList = await client.prompts().catch(() => [])
+          const promptMessages: Array<unknown> = []
+          for (const p of promptList) {
+            const got = await client.getPrompt(p.name)
+            promptMessages.push(...mcpPromptToMessages(got))
+          }
+
+          return Response.json({
+            tools,
+            resources: resourceList.map((r) => r.uri),
+            prompts: promptList.map((p) => p.name),
+            resourceContent,
+            promptMessages,
+          })
+        } finally {
+          await client.close()
+        }
+      },
+    },
+  },
+})
diff --git a/testing/e2e/src/routes/api.mcp-test.ts b/testing/e2e/src/routes/api.mcp-test.ts
new file mode 100644
index 000000000..a6ea991a7
--- /dev/null
+++ b/testing/e2e/src/routes/api.mcp-test.ts
@@ -0,0 +1,136 @@
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  chat,
+  chatParamsFromRequestBody,
+  maxIterations,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import type { StreamChunk } from '@tanstack/ai'
+import type { MCPClient } from '@tanstack/ai-mcp'
+import { createTextAdapter } from '@/lib/providers'
+
+/**
+ * Wrap the chat stream so the MCP client is closed only AFTER the stream has
+ * fully drained (or errored). Tool calls fire mid-stream, so closing the
+ * client earlier would abort an in-flight MCP tool call.
+ */
+async function* closeMcpOnDrain(
+  stream: AsyncIterable<StreamChunk>,
+  mcp: MCPClient,
+): AsyncGenerator<StreamChunk> {
+  try {
+    for await (const chunk of stream) {
+      yield chunk
+    }
+  } finally {
+    await mcp.close()
+  }
+}
+
+/**
+ * Drives a real `chat()` agent loop whose tools are discovered from the
+ * in-process mock MCP server (`api.mcp-server`) via `@tanstack/ai-mcp`.
+ *
+ * Flow:
+ *   1. `createMCPClient({ transport: { type: 'http', url } })` connects to the
+ *      mock MCP server at this dev server's own origin.
+ *   2. `mcp.tools()` auto-discovers the server's tools (here: `get_guitar_price`)
+ *      as TanStack `ServerTool`s whose `execute` proxies to the MCP server.
+ *   3. `chat()` runs the OpenAI adapter against aimock. The aimock fixture
+ *      emits a `get_guitar_price` tool call; the MCP tool executes for real
+ *      against the mock server, returning `{ id, price: 1999 }`; the result is
+ *      fed back and the model emits a final answer mentioning the price.
+ *   4. The MCP client is closed in `finally` AFTER the stream fully drains —
+ *      closing earlier would kill the connection mid tool-call.
+ */
+export const Route = createFileRoute('/api/mcp-test')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        if (request.signal.aborted) {
+          return new Response(null, { status: 499 })
+        }
+
+        const abortController = new AbortController()
+        // Bridge request cancellation into the chat abort controller so an
+        // abort during setup (before the SSE handoff) is observed.
+        const onRequestAbort = () => abortController.abort()
+        request.signal.addEventListener('abort', onRequestAbort, {
+          once: true,
+        })
+
+        let params
+        try {
+          params = await chatParamsFromRequestBody(await request.json())
+        } catch (error) {
+          return new Response(
+            error instanceof Error ? error.message : 'Bad request',
+            { status: 400 },
+          )
+        }
+
+        const fp = params.forwardedProps
+        const testId = typeof fp.testId === 'string' ? fp.testId : undefined
+        const aimockPort =
+          fp.aimockPort != null ? Number(fp.aimockPort) : undefined
+
+        // The mock MCP server lives at this same dev server's origin.
+        const origin = new URL(request.url).origin
+        const mcpUrl = `${origin}/api/mcp-server`
+
+        // Held in the outer scope so the catch below can close it on any
+        // error path that happens before the SSE stream takes ownership.
+        let mcp: MCPClient | undefined
+        try {
+          mcp = await createMCPClient({
+            transport: { type: 'http', url: mcpUrl },
+          })
+
+          const tools = await mcp.tools()
+
+          const adapterOptions = createTextAdapter(
+            'openai',
+            undefined,
+            aimockPort,
+            testId,
+          )
+
+          const stream = chat({
+            ...adapterOptions,
+            messages: params.messages,
+            tools,
+            threadId: params.threadId,
+            runId: params.runId,
+            agentLoopStrategy: maxIterations(5),
+            abortController,
+          })
+
+          // Close the MCP client only after the SSE stream fully drains —
+          // tool calls fire mid-stream, so an early close would abort them.
+          return toServerSentEventsResponse(closeMcpOnDrain(stream, mcp), {
+            abortController,
+          })
+        } catch (error) {
+          // The stream never took ownership of the client — close it here.
+          if (mcp) {
+            await mcp.close().catch(() => undefined)
+          }
+          console.error('[api.mcp-test] Error:', error)
+          if (
+            (error instanceof Error && error.name === 'AbortError') ||
+            abortController.signal.aborted
+          ) {
+            return new Response(null, { status: 499 })
+          }
+          const message =
+            error instanceof Error ? error.message : 'An error occurred'
+          return new Response(JSON.stringify({ error: message }), {
+            status: 500,
+            headers: { 'Content-Type': 'application/json' },
+          })
+        }
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/mcp-lifecycle.spec.ts b/testing/e2e/tests/mcp-lifecycle.spec.ts
new file mode 100644
index 000000000..9157d1f82
--- /dev/null
+++ b/testing/e2e/tests/mcp-lifecycle.spec.ts
@@ -0,0 +1,80 @@
+import { test, expect } from './fixtures'
+
+/**
+ * `chat({ mcp: { connection } })` lifecycle semantics, end-to-end.
+ *
+ * `api.mcp-lifecycle-test` runs a real chat() agent loop with one MCP client,
+ * drains it, then probes whether the client is still usable:
+ *   - 'close' (default) → chat closed it → not usable.
+ *   - 'keep-alive'      → chat left it open → still usable.
+ *
+ * The unit tests assert this against fake sources; this proves it against a
+ * real `createMCPClient` over Streamable HTTP. aimock returns a plain text turn
+ * (fixtures/mcp/lifecycle.json) — no tool call needed; only lifecycle matters.
+ */
+async function runLifecycle(
+  request: import('@playwright/test').APIRequestContext,
+  opts: {
+    testId: string
+    aimockPort: number
+    connection: 'close' | 'keep-alive'
+  },
+) {
+  const res = await request.post('/api/mcp-lifecycle-test', {
+    headers: { 'Content-Type': 'application/json' },
+    data: {
+      threadId: `mcp-life-${opts.testId}`,
+      runId: `mcp-life-run-${opts.testId}`,
+      state: {},
+      messages: [
+        { id: 'mcp-life-msg-1', role: 'user', content: '[mcp-lifecycle] ping' },
+      ],
+      tools: [],
+      context: [],
+      forwardedProps: {
+        testId: opts.testId,
+        aimockPort: opts.aimockPort,
+        connection: opts.connection,
+      },
+    },
+  })
+  const body = await res.text()
+  expect(
+    res.ok(),
+    `mcp-lifecycle-test (${opts.connection}) failed (${res.status()}): ${body}`,
+  ).toBe(true)
+  return JSON.parse(body) as {
+    connection: string
+    survivedAfterRun: boolean
+  }
+}
+
+test.describe('mcp — chat({ mcp }) connection lifecycle', () => {
+  test("connection: 'close' (default) closes the client after the run", async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const json = await runLifecycle(request, {
+      testId: `${testId}-close`,
+      aimockPort,
+      connection: 'close',
+    })
+    expect(json.connection).toBe('close')
+    expect(json.survivedAfterRun).toBe(false)
+  })
+
+  test("connection: 'keep-alive' leaves the client open after the run", async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const json = await runLifecycle(request, {
+      testId: `${testId}-keepalive`,
+      aimockPort,
+      connection: 'keep-alive',
+    })
+    expect(json.connection).toBe('keep-alive')
+    expect(json.survivedAfterRun).toBe(true)
+  })
+})
diff --git a/testing/e2e/tests/mcp-managed.spec.ts b/testing/e2e/tests/mcp-managed.spec.ts
new file mode 100644
index 000000000..dd688041d
--- /dev/null
+++ b/testing/e2e/tests/mcp-managed.spec.ts
@@ -0,0 +1,116 @@
+import { test, expect } from './fixtures'
+
+/**
+ * MCP tool discovery + execution managed by `chat({ mcp })`.
+ *
+ * Proves that passing `mcp: { clients, connection: 'close' }` to `chat()` is
+ * sufficient to:
+ *   1. Auto-discover tools from the MCP client (no manual `mcp.tools()` call).
+ *   2. Execute the discovered tool (`get_guitar_price`) inside the agent loop.
+ *   3. Close the MCP client after the stream drains (no manual `mcp.close()`).
+ *
+ * The route under test (`api.mcp-managed-test`) does NOT call `mcp.tools()` or
+ * `mcp.close()` — it delegates both to `chat({ mcp })`. Compare with
+ * `api.mcp-test`, which manually calls `mcp.tools()` and wraps the stream in a
+ * `closeMcpOnDrain` generator.
+ *
+ * Same fixture as the basic MCP test (`fixtures/mcp/basic.json`). Each test
+ * gets a unique `testId` so `sequenceIndex` is isolated between the two specs.
+ */
+
+type StreamEvent = {
+  type: string
+  toolName?: string
+  toolCallName?: string
+  toolCallId?: string
+  result?: unknown
+  content?: unknown
+  delta?: string
+}
+
+function parseSse(body: string): Array<StreamEvent> {
+  const events: Array<StreamEvent> = []
+  for (const line of body.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('data:')) continue
+    const json = trimmed.slice('data:'.length).trim()
+    if (!json) continue
+    try {
+      events.push(JSON.parse(json) as StreamEvent)
+    } catch {
+      // Ignore non-JSON keepalive lines.
+    }
+  }
+  return events
+}
+
+test.describe('mcp-managed — chat({ mcp }) discovery + lifecycle', () => {
+  test('chat({ mcp }) discovers get_guitar_price and the result reaches the transcript', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    // Minimal valid AG-UI RunAgentInput body — identical message to the basic
+    // MCP spec so the same aimock fixture (`fixtures/mcp/basic.json`) is used.
+    // Unique testId ensures sequenceIndex isolation from the other spec.
+    const res = await request.post('/api/mcp-managed-test', {
+      headers: { 'Content-Type': 'application/json' },
+      data: {
+        threadId: `mcp-managed-thread-${testId}`,
+        runId: `mcp-managed-run-${testId}`,
+        state: {},
+        messages: [
+          {
+            id: 'mcp-managed-msg-1',
+            role: 'user',
+            content: '[mcp] how much is the strat guitar',
+          },
+        ],
+        tools: [],
+        context: [],
+        forwardedProps: { testId, aimockPort },
+      },
+    })
+
+    const body = await res.text()
+    expect(
+      res.ok(),
+      `mcp-managed-test route failed (${res.status()}): ${body}`,
+    ).toBe(true)
+
+    const events = parseSse(body)
+
+    // The agentic loop must have invoked the MCP tool via chat({ mcp }) discovery.
+    const toolStart = events.find(
+      (e) =>
+        e.type === 'TOOL_CALL_START' &&
+        (e.toolName === 'get_guitar_price' ||
+          e.toolCallName === 'get_guitar_price'),
+    )
+    expect(
+      toolStart,
+      'expected a TOOL_CALL_START for get_guitar_price',
+    ).toBeTruthy()
+
+    // The MCP tool result is emitted as the AG-UI TOOL_CALL_RESULT event. The
+    // price 1999 originates ONLY from the real MCP server (the fixture's
+    // tool-call args don't contain it), so finding it here proves the MCP tool
+    // actually executed against the in-process server via chat({ mcp }).
+    const toolResult = events.find((e) => e.type === 'TOOL_CALL_RESULT')
+    expect(toolResult, 'expected a TOOL_CALL_RESULT event').toBeTruthy()
+    const resultStr = JSON.stringify(toolResult?.content ?? '')
+    expect(resultStr).toContain('1999')
+    expect(resultStr).toContain('strat')
+
+    // The final assistant text (post tool execution) must contain the price too.
+    const finalText = events
+      .filter((e) => e.type === 'TEXT_MESSAGE_CONTENT' && e.delta)
+      .map((e) => e.delta)
+      .join('')
+    expect(finalText).toContain('1999')
+
+    // The run completed cleanly (no RUN_ERROR).
+    expect(events.some((e) => e.type === 'RUN_ERROR')).toBe(false)
+    expect(events.some((e) => e.type === 'RUN_FINISHED')).toBe(true)
+  })
+})
diff --git a/testing/e2e/tests/mcp-status.spec.ts b/testing/e2e/tests/mcp-status.spec.ts
new file mode 100644
index 000000000..942be3e5f
--- /dev/null
+++ b/testing/e2e/tests/mcp-status.spec.ts
@@ -0,0 +1,52 @@
+import { test, expect } from './fixtures'
+
+/**
+ * MCP resource + prompt read/convert path, end-to-end against the in-process
+ * Streamable-HTTP MCP server (`api.mcp-server`).
+ *
+ * `api.mcp-status-test` connects via `@tanstack/ai-mcp`, lists + reads the
+ * server's tools/resources/prompts, and converts resources/prompts through the
+ * public `mcpResourceToContentPart` / `mcpPromptToMessages` helpers. This proves
+ * the manual-integration building blocks (resources(), readResource(),
+ * prompts(), getPrompt() + converters) work against a real server — the unit
+ * tests only cover the converters in isolation. No LLM is involved.
+ */
+test.describe('mcp — resource/prompt discovery + conversion', () => {
+  test('lists and converts the server tools, resources, and prompts', async ({
+    request,
+  }) => {
+    const res = await request.get('/api/mcp-status-test')
+    const body = await res.text()
+    expect(
+      res.ok(),
+      `mcp-status-test route failed (${res.status()}): ${body}`,
+    ).toBe(true)
+
+    const json = JSON.parse(body) as {
+      tools: Array<string>
+      resources: Array<string>
+      prompts: Array<string>
+      resourceContent: Array<{ type: string; content: string }>
+      promptMessages: Array<{ role: string; content: string }>
+    }
+
+    // Tool discovered.
+    expect(json.tools).toContain('get_guitar_price')
+
+    // Task-required tool (execution.taskSupport: 'required') is excluded from
+    // discovery — plain callTool can never execute it (-32600).
+    expect(json.tools).not.toContain('appraise_guitar_collection')
+
+    // Resource listed + read + converted to a text ContentPart carrying the
+    // server's distinctive token.
+    expect(json.resources).toContain('guitar://catalog')
+    const resourceText = json.resourceContent.map((c) => c.content).join('\n')
+    expect(resourceText).toContain('STRAT-001')
+
+    // Prompt listed + fetched + converted to ModelMessages.
+    expect(json.prompts).toContain('recommend_guitar')
+    expect(json.promptMessages.length).toBeGreaterThan(0)
+    const promptText = json.promptMessages.map((m) => m.content).join('\n')
+    expect(promptText.toLowerCase()).toContain('guitar')
+  })
+})
diff --git a/testing/e2e/tests/mcp.spec.ts b/testing/e2e/tests/mcp.spec.ts
new file mode 100644
index 000000000..148662c4a
--- /dev/null
+++ b/testing/e2e/tests/mcp.spec.ts
@@ -0,0 +1,115 @@
+import { test, expect } from './fixtures'
+
+/**
+ * MCP server tool discovery + execution inside chat().
+ *
+ * Proves the `@tanstack/ai-mcp` package end-to-end against the real E2E
+ * harness:
+ *   - `api.mcp-server` hosts a real in-process MCP server (Streamable HTTP)
+ *     exposing one deterministic tool `get_guitar_price` ({ id } → { id,
+ *     price: 1999 }).
+ *   - `api.mcp-test` connects to it via `createMCPClient`, discovers the tool
+ *     with `mcp.tools()`, and runs it inside a real `chat()` agent loop with
+ *     the LLM mocked by aimock.
+ *   - The aimock fixture (`fixtures/mcp/basic.json`) makes the model emit a
+ *     `get_guitar_price` tool call then a final answer.
+ *
+ * The MCP server is the *only* source of the price `1999`: the fixture's
+ * tool-call arguments don't contain it. So asserting `1999` reaches the
+ * streamed `TOOL_CALL_END.result` proves the MCP tool actually executed.
+ */
+
+type StreamEvent = {
+  type: string
+  toolName?: string
+  toolCallName?: string
+  toolCallId?: string
+  result?: unknown
+  content?: unknown
+  delta?: string
+}
+
+function parseSse(body: string): Array<StreamEvent> {
+  const events: Array<StreamEvent> = []
+  for (const line of body.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('data:')) continue
+    const json = trimmed.slice('data:'.length).trim()
+    if (!json) continue
+    try {
+      events.push(JSON.parse(json) as StreamEvent)
+    } catch {
+      // Ignore non-JSON keepalive lines.
+    }
+  }
+  return events
+}
+
+test.describe('mcp — server tool discovery + execution in chat()', () => {
+  test('discovers get_guitar_price from the MCP server and the result reaches the transcript', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    // Minimal valid AG-UI RunAgentInput body (the route parses it via
+    // chatParamsFromRequestBody).
+    const res = await request.post('/api/mcp-test', {
+      headers: { 'Content-Type': 'application/json' },
+      data: {
+        threadId: `mcp-thread-${testId}`,
+        runId: `mcp-run-${testId}`,
+        state: {},
+        messages: [
+          {
+            id: 'mcp-msg-1',
+            role: 'user',
+            content: '[mcp] how much is the strat guitar',
+          },
+        ],
+        tools: [],
+        context: [],
+        forwardedProps: { testId, aimockPort },
+      },
+    })
+
+    const body = await res.text()
+    expect(res.ok(), `mcp-test route failed (${res.status()}): ${body}`).toBe(
+      true,
+    )
+
+    const events = parseSse(body)
+
+    // The agentic loop must have invoked the MCP tool.
+    const toolStart = events.find(
+      (e) =>
+        e.type === 'TOOL_CALL_START' &&
+        (e.toolName === 'get_guitar_price' ||
+          e.toolCallName === 'get_guitar_price'),
+    )
+    expect(
+      toolStart,
+      'expected a TOOL_CALL_START for get_guitar_price',
+    ).toBeTruthy()
+
+    // The MCP tool result is emitted as the AG-UI TOOL_CALL_RESULT event. The
+    // price 1999 originates ONLY from the real MCP server (the fixture's
+    // tool-call args don't contain it), so finding it here proves the MCP tool
+    // actually executed against the in-process server.
+    const toolResult = events.find((e) => e.type === 'TOOL_CALL_RESULT')
+    expect(toolResult, 'expected a TOOL_CALL_RESULT event').toBeTruthy()
+    const resultStr = JSON.stringify(toolResult?.content ?? '')
+    expect(resultStr).toContain('1999')
+    expect(resultStr).toContain('strat')
+
+    // And the final assistant text (post tool execution) streamed through.
+    const finalText = events
+      .filter((e) => e.type === 'TEXT_MESSAGE_CONTENT' && e.delta)
+      .map((e) => e.delta)
+      .join('')
+    expect(finalText).toContain('1999')
+
+    // The run completed cleanly (no RUN_ERROR).
+    expect(events.some((e) => e.type === 'RUN_ERROR')).toBe(false)
+    expect(events.some((e) => e.type === 'RUN_FINISHED')).toBe(true)
+  })
+})