feat(ai, ai-mcp): send request-scoped _meta with MCP requests

.changeset/mcp-request-meta.md

@@ -0,0 +1,8 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-mcp': minor
+---
+
+Send request context to MCP servers as `_meta`. Set `requestMeta` on `chat({ mcp })` or `tools()`, or pass `meta` to `callTool`, `readResource`, `getPrompt`, and the MCP Apps call handler.
+
+`createMCPClients().readResource(uri, { serverId })` now reads only from the server with that key.

docs/config.json

@@ -636,13 +636,13 @@
           "label": "Managed MCP with chat()",
           "to": "tools/mcp-managed",
           "addedAt": "2026-06-05",
-          "updatedAt": "2026-11-02"
+          "updatedAt": "2026-11-09"
         },
         {
           "label": "Manual MCP",
           "to": "tools/mcp-manual",
           "addedAt": "2026-06-05",
-          "updatedAt": "2026-11-02"
+          "updatedAt": "2026-11-09"
         },
         {
           "label": "MCP Type Generation",
@@ -670,7 +670,7 @@
           "label": "MCP Apps",
           "to": "mcp/apps",
           "addedAt": "2026-06-24",
-          "updatedAt": "2026-11-02"
+          "updatedAt": "2026-11-09"
         },
         {
           "label": "Serve Tools over HTTP",

docs/mcp/apps.md

@@ -368,6 +368,51 @@ const handler = createMcpAppCallHandler({
 
 `phase` is `'call'` for a failure to connect, find, or run the tool. It is `'close'` for a failure to close the client after the call. A `'close'` failure does not change the result.
 
+### Send request context with widget calls
+
+Pass `meta` to the handler in your call route. The handler sends it as the `_meta` of the widget tool call:
+
+```ts ignore
+// src/routes/api.mcp-apps-call.ts  (TanStack Start)
+import { createFileRoute } from '@tanstack/react-router'
+import { createMCPClients } from '@tanstack/ai-mcp'
+import { createMcpAppCallHandler } from '@tanstack/ai-mcp/apps'
+
+const mcp = await createMCPClients({
+  weather: { transport: { type: 'http', url: process.env.WEATHER_MCP_URL ?? '' } },
+})
+
+const handler = createMcpAppCallHandler({ clients: mcp })
+
+export const Route = createFileRoute('/api/mcp-apps/call')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const body = await request.json()
+        const result = await handler(body, {
+          signal: request.signal,
+          // Use the same keys as the requestMeta of your chat route.
+          // Your auth gateway sets these headers after it checks the user.
+          meta: {
+            'acme.com/tenantId': request.headers.get('x-tenant-id'),
+            'acme.com/traceId': request.headers.get('x-trace-id'),
+          },
+        })
+        return new Response(JSON.stringify(result), {
+          headers: { 'Content-Type': 'application/json' },
+        })
+      },
+    },
+  },
+})
+```
+
+- A widget call is a new HTTP request, outside the `chat()` run. So the `requestMeta` of `chat()` does not reach it. Read the context from this request.
+- Only the `tools/call` gets the `_meta`. The connect and the tool list do not.
+- In the chat route, set `requestMeta` so that the `ui://` read of the widget gets the same context. See [Send request context to MCP servers](../tools/mcp-managed#send-request-context-to-mcp-servers).
+
+Now the server sees the same tenant on the chat tool call, the widget read, and each widget call.
+
 ### Links from a widget
 
 - If you pass no `onLink`, the bridge drops the link and logs a warning. `openLink` returns `{ isError: true }`, and the call does not hang.
@@ -409,7 +454,7 @@ const handler = createMcpAppCallHandler({ clients: mcp, store })
 
 ### API reference
 
-`createMcpAppCallHandler(options)` from `@tanstack/ai-mcp/apps` returns `(req) => Promise<{ ok: true; result: unknown } | { ok: false; error: string }>`.
+`createMcpAppCallHandler(options)` from `@tanstack/ai-mcp/apps` returns `(req, { signal?, meta? }?) => Promise<{ ok: true; result: unknown } | { ok: false; error: string }>`.
 
 | Option | Type | Description |
 | --- | --- | --- |

docs/tools/mcp-managed.md

@@ -14,6 +14,7 @@ keywords:
   - onDiscoveryError
   - toolFilter
   - needsApproval
+  - requestMeta
 ---
 
 Pass MCP clients to `chat()` in the `mcp` option. `chat()` loads their tools and closes the clients when the run ends.
@@ -171,6 +172,82 @@ A `toolFilter` list is strict. If the server has no tool with a listed name, or
 > [!WARNING]
 > The hints come from the server, and a compromised server can send false hints. For the trust rules and the list form, see [Limit and Gate Tools](./mcp-advanced#limit-and-gate-tools).
 
+## Send request context to MCP servers
+
+Set `requestMeta` on `chat({ mcp })`. `chat()` sends its result as `_meta` with each MCP tool call and each MCP Apps `ui://` read in this run.
+
+Often the MCP server must know who calls: the tenant, the user, or the trace. A shared pool connects once, so its headers are the same for all requests. `_meta` goes with each request, on every transport.
+
+```ts
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClients } from '@tanstack/ai-mcp'
+
+// Made once when the module loads. All requests share it.
+const sharedPool = await createMCPClients({
+  internal: { transport: { type: 'http', url: process.env.INTERNAL_MCP_URL! } },
+  github: { transport: { type: 'http', url: process.env.GITHUB_MCP_URL! } },
+})
+
+export async function POST(request: Request) {
+  const { messages, threadId, runId } = await chatParamsFromRequest(request)
+  // Your auth gateway sets these headers after it checks the user.
+  const tenantId = request.headers.get('x-tenant-id')
+  const traceId = request.headers.get('x-trace-id')
+
+  const stream = chat({
+    adapter: openaiText('gpt-6.1-sol'),
+    messages,
+    threadId,
+    runId,
+    mcp: {
+      clients: [sharedPool],
+      connection: 'keep-alive',
+      // Send the context to the internal server only
+      requestMeta: ({ serverId }) =>
+        serverId === 'internal'
+          ? { 'acme.com/tenantId': tenantId, 'acme.com/traceId': traceId }
+          : undefined,
+    },
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+Your `useChat` code does not change. For why the pool is made once, see [Keep connections warm](#keep-connections-warm).
+
+How the hook works:
+
+- It runs once for each MCP request, when the request starts. Tool discovery does not call it.
+- It gets `method` and `serverId`. A `tools/call` also has `toolName` and `args`. A `resources/read` has `uri`. In a `createMCPClients` pool, `serverId` is the config key.
+- Return `undefined` to send no `_meta`.
+- The client removes the keys that MCP reserves: `progressToken`, and keys with a prefix like `io.modelcontextprotocol/` or `mcp.dev/`.
+- If the hook throws, only that request fails. A tool call goes to the model as a tool error. A `ui://` read fails, and the message has no widget.
+
+On the server, an MCP SDK request handler finds the object in `request.params._meta`.
+
+`_meta` is not part of the [`toolCacheMiddleware`](../advanced/built-in-middleware#toolcachemiddleware) key. A cache hit sends no request, so the hook does not run. If tenants share one cache storage, put the tenant in `keyFn`:
+
+```ts
+import {
+  toolCacheMiddleware,
+  type ToolCacheStorage,
+} from '@tanstack/ai/middlewares'
+
+// Make the middleware in the route, with the tenant of the request
+export function tenantToolCache(tenantId: string, storage: ToolCacheStorage) {
+  return toolCacheMiddleware({
+    storage,
+    keyFn: (toolName, args) => JSON.stringify([tenantId, toolName, args]),
+  })
+}
+```
+
 ## Keep connections warm
 
 A new MCP connection on each request adds latency. On a busy route, make the pool once at module level and pass `connection: 'keep-alive'`. Then `chat()` never closes the pool, and the next request uses the same connections.

docs/tools/mcp-manual.md

@@ -297,6 +297,71 @@ export const Route = createFileRoute('/api/chat')({
 | Any other role | `{ role: 'user', content: text }` |
 | Content that is not text | `content` is the `JSON.stringify` output |
 
+## Send request context
+
+Pass `meta` to `callTool`, `readResource`, or `getPrompt`. The client sends it as the `_meta` of that request, so the MCP server knows who calls:
+
+```ts
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+const mcp = await createMCPClient({
+  transport: { type: 'http', url: process.env.MCP_URL! },
+})
+
+const meta = { 'acme.com/tenantId': 'tenant-42', 'acme.com/traceId': 'trace-7' }
+
+const result = await mcp.callTool('search', { query: 'invoices' }, { meta })
+const doc = await mcp.readResource('docs://handbook', { meta })
+const prompt = await mcp.getPrompt('summarize', { language: 'english' }, { meta })
+console.log(result.content, doc.contents, prompt.messages)
+```
+
+`meta` goes on that one request only. The client sends no `_meta` with `tools/list`, `resources/list`, or `prompts/list`.
+
+On a `createMCPClients` pool, `readResource(uri, { serverId, meta })` reads only from the server with that config key. The other servers do not get the `_meta`.
+
+### Context for tools that you pass to chat()
+
+Set `requestMeta` on `tools()`. Each call of the returned tools runs the hook and sends its result as `_meta`. Call `tools()` once for each request, so the hook stays with that request:
+
+```ts
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+// Made once when the module loads. All requests share it.
+const mcp = await createMCPClient({
+  transport: { type: 'http', url: process.env.MCP_URL! },
+})
+
+export async function POST(request: Request) {
+  const { messages, threadId, runId } = await chatParamsFromRequest(request)
+  // Your auth gateway sets this header after it checks the user.
+  const tenantId = request.headers.get('x-tenant-id')
+
+  // New tools for this request. Each tool call sends this tenant.
+  const tools = await mcp.tools({
+    requestMeta: () => ({ 'acme.com/tenantId': tenantId }),
+  })
+
+  const stream = chat({
+    adapter: openaiText('gpt-6.1-sol'),
+    messages,
+    threadId,
+    runId,
+    tools,
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+With typed tools, pass the options second: `mcp.tools([searchDef], { requestMeta })`. For what the hook gets and which keys the client removes, see [Send request context to MCP servers](./mcp-managed#send-request-context-to-mcp-servers).
+
 ## Cancellation
 
 A chat run can stop, for example when the user leaves the page or an `AbortController` fires. Then TanStack AI stops the wait for MCP tool calls in progress. The abort signal of the run goes to the execute function of each tool in `ToolExecutionContext.abortSignal`.

packages/ai-mcp/src/apps/call-handler.ts

@@ -217,6 +217,12 @@ export function createMcpAppCallHandler(opts: McpAppCallHandlerOptions) {
     options?: {
       /** Cancels the connect, the tool list, and the tool call. */
       signal?: AbortSignal
+      /**
+       * Sent as the `_meta` of the proxied `tools/call`. Pass the request
+       * context of the HTTP request that carries this widget call (tenant,
+       * trace).
+       */
+      meta?: Record<string, unknown>
     },
   ): Promise<{ ok: true; result: unknown } | { ok: false; error: string }> => {
     const signal = options?.signal
@@ -300,8 +306,9 @@ export function createMcpAppCallHandler(opts: McpAppCallHandlerOptions) {
       if (!isArgsRecord(args)) {
         return { ok: false, error: 'Invalid args: expected an object' }
       }
-      const result = signal
-        ? await client.callTool(req.toolName, args, { signal })
+      // Only the tools/call gets the meta. The connect and tools/list do not.
+      const result = options
+        ? await client.callTool(req.toolName, args, options)
         : await client.callTool(req.toolName, args)
       return { ok: true, result }
     } catch (err) {