Request-scoped _meta on MCP tool calls from chat()

[OAmsalem2002]

Problem

I use chat({ mcp }) with a shared createMCPClients pool, created once at module load. I need to send per-request context to MCP servers on each tool call: tenant and user ids, trace ids, and structured data.

Today the only option is headers via a custom transport:

• it doesn't work over stdio
• it only carries strings
• it is fixed when the shared pool is created, so it can't carry per-request values

Putting the values in tool args is worse: the model sees them and can change them.

MCP's request _meta solves this on every transport, because it is part of the JSON-RPC params.

Option A: toolCallMeta on chat({ mcp })

chat({
  adapter,
  messages,
  mcp: {
    clients: [pool],
    toolCallMeta: ({ serverId, toolName, args }) => ({
      'acme.com/tenantId': session.tenantId,
      'acme.com/traceId': traceId,
    }),
  },
})

• chat() runs once per request, so this is request-scoped with no extra plumbing, even on a shared pool.
• It gets serverId and toolName, so the caller can send context only to the servers that should get it. A pool can mix internal and third-party servers.
• It may return an object, undefined, or a Promise of either.
• Keys the spec reserves, such as progressToken, are not overwritten.

Option B: onBeforeToolCall returns meta

import { defineMiddleware } from '@tanstack/ai'

type RequestContext = { tenantId: string; traceId: string }

export const mcpRequestMeta = defineMiddleware<RequestContext>({
  name: 'mcp-request-meta',
  onBeforeToolCall: (ctx, hookCtx) => {
    // Pool prefix for the internal server, e.g. createMCPClients({ internal: ... })
    if (!hookCtx.toolName.startsWith('internal_')) return

    const { tenantId, traceId } = ctx.context
    return {
      type: 'meta',
      meta: {
        'acme.com/tenantId': tenantId,
        'acme.com/traceId': traceId,
      },
    }
  },
})

Let the existing middleware hook return meta for MCP tools. This reuses an existing API, and because middleware runs for every tool call, it also covers manual mode. LangChain JS took a similar path in @langchain/mcp-adapters.

The main open question: today the first middleware that returns a decision from onBeforeToolCall ends the chain for that call. A meta decision must not do that, or it would block later middleware such as toolCacheMiddleware (or be blocked by it). So meta would need to be a non-terminal decision. Riding on transformArgs wouldn't avoid this on its own, since transformArgs also ends the chain. A separate piped hook (like onConfig) is another option. It also puts MCP-specific behaviour in core middleware.

Things I've thought about

• When it runs (Option A): at execution time, after onBeforeToolCall. A toolCacheMiddleware hit skips the call, so no meta is computed.
• Tool cache: meta is not part of the cache key. With shared cache storage, users should include the same context in keyFn. I'd document this.
• Implementation: MCP tool calls go through the SDK Client.callTool, whose params accept _meta, so there's a natural place to pass it through.

Out of scope (for now)

• Manual mode for Option A (tools: [...await mcp.tools()]): chat() never sees the MCP config there.
• tools/list meta: discovery may be cached or shared across runs, so request-scoped meta could leak between runs.
• Resources and prompts: chat() doesn't request them.

Questions

1. Option A or B, or something else?
2. Is the name toolCallMeta OK?
3. If Option A, should manual mode get a matching option later? (Option B covers it already.)

Happy to go whichever direction you prefer.