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

.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`).

.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.

.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.

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"
         }
       ]
     },

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.