ai-mcp: modern tool calls omit x-mcp-header parameter headers in 0.9.0

Start in src/tools.ts, where callMcpTool sends modern calls through rawRequest, and in src/client.ts, where tools/list is requested directly. Run the inline Deno repro to confirm Mcp-Param-Region is missing from tools/call headers. Done when a discovered tool with an x-mcp-header argument sends the matching Mcp-Param header and the strict fixture passes, with input-required handling still working.

TanStack AI version

@tanstack/[email protected]. The same behavior was observed with 0.8.3.

Framework/Library version

@modelcontextprotocol/[email protected], Deno 2.9.7, TypeScript 6.0.3, macOS arm64. The reproduction calls the MCP client directly and does not require React, an AI model, or a chat framework.

Describe the bug and the steps to reproduce it

Modern MCP tool calls made through createMCPClient().tools() omit the HTTP headers required by a tool's x-mcp-header input-schema annotations. The JSON arguments and standard Mcp-Name header are present, but the corresponding Mcp-Param-* headers are absent.

This breaks tools on GitHub's remote MCP server that declare owner and repo with x-mcp-header. For example, get_file_contents is rejected with HTTP 400, JSON-RPC error -32020, because Mcp-Param-owner and Mcp-Param-repo are missing. Discovery and tools without those annotated arguments, such as get_me and search_code, can succeed on the same connection. This is therefore easy to miss in a connection or basic tool smoke test.

1. Connect using MCP protocol 2026-07-28 and StreamableHTTPClientTransport.
2. Discover a tool whose input schema contains region: { type: "string", "x-mcp-header": "Region" }.
3. Execute the discovered TanStack tool with { region: "eu" }.
4. Inspect the outgoing tools/call headers. Mcp-Param-Region is missing.
5. Repeat with the same transport fixture and native SDK Client.listTools() / Client.callTool(). The SDK sends Mcp-Param-Region: eu.

Expected: the TanStack adapter preserves the SDK's schema-driven header mirroring, so the same tool can be called successfully through either client.

Reproduced after installing @tanstack/[email protected]. The fixture rejects a missing or mismatched header with HTTP 400 and error code -32020. Each path sent one tools/call:

Minimal reproducible example

The complete tested example is inline below. Save it as header-repro.mts and run it with Deno after resolving the pinned npm dependencies. It uses fake fetch responses and needs no MCP server, GitHub account, credentials, or AI model.

import { createMCPClient } from "npm:@tanstack/[email protected]"
import { Client, StreamableHTTPClientTransport } from "npm:@modelcontextprotocol/[email protected]"

const tool = {
  name: "lookup",
  inputSchema: {
    type: "object" as const,
    properties: { region: { type: "string", "x-mcp-header": "Region" } },
    required: ["region"],
  },
}

async function reproduce(kind: "tanstack" | "native") {
  const calls: unknown[] = []
  const transport = new StreamableHTTPClientTransport(new URL("https://fixture.example/mcp"), {
    protocolVersion: "2026-07-28",
    fetch: async (_url, init) => {
      const body = JSON.parse(String(init?.body))
      const headers = new Headers(init?.headers)
      if (body.method === "tools/call") {
        const region = headers.get("Mcp-Param-Region")
        calls.push({ method: body.method, name: headers.get("Mcp-Name"), region })
        if (region !== body.params.arguments.region)
          return Response.json({ jsonrpc: "2.0", id: body.id, error: {
            code: -32020, message: "Missing or mismatched Mcp-Param-Region header",
          } }, { status: 400 })
      }
      const result = body.method === "server/discover"
        ? { supportedVersions: ["2026-07-28"], serverInfo: { name: "fixture", version: "1" }, capabilities: { tools: {} } }
        : body.method === "tools/list"
          ? { tools: [tool] }
          : { content: [{ type: "text", text: "ok" }] }
      return Response.json({ jsonrpc: "2.0", id: body.id, result: {
        resultType: "complete", ttlMs: 0, cacheScope: "private", ...result,
      } })
    },
  })
  let client: { close(): Promise<void> } | undefined
  try {
    if (kind === "tanstack") {
      const mcp = await createMCPClient({ transport })
      client = mcp
      const [remote] = await mcp.tools()
      await remote!.execute!({ region: "eu" }, undefined)
    } else {
      const mcp = new Client({ name: "control", version: "1" }, {
        versionNegotiation: { mode: { pin: "2026-07-28" } },
      })
      client = mcp
      await mcp.connect(transport)
      await mcp.listTools()
      await mcp.callTool({ name: "lookup", arguments: { region: "eu" } })
    }
    return { kind, success: true, calls }
  } catch (error) {
    return { kind, success: false, calls, error: String(error) }
  } finally {
    await client?.close()
  }
}

console.log(JSON.stringify(await Promise.all([reproduce("tanstack"), reproduce("native")]), null, 2))

Cause identified in the published source

In @tanstack/[email protected]/src/tools.ts, callMcpTool sends modern calls through rawRequest, which calls transport.send(message) directly without send options. This bypasses Client.callTool, where SDK 2.3.1 derives the Mcp-Param-* headers from the tool definition. The transport adds standard protocol headers but cannot derive argument-specific headers without the schema.

Modern discovery in src/client.ts also uses a raw tools/list request rather than native Client.listTools(). A fix that routes calls through the SDK should therefore also populate its tool-definition cache or pass the explicit tool definition. The Streamable HTTP specification describes these required headers and their encoding.

The same rawRequest call also omits the transport's requestSignal option. It listens for abort to settle its own promise, but does not forward that signal through this send call. This is an adjacent source observation, not needed to reproduce the header failure, and may warrant separate cancellation coverage.

Possible fix and regression coverage

Could modern calls use the native SDK Client.callTool with the discovered toolDefinition and allowInputRequired: true, while preserving the adapter's manual input-required handling? This is a suggested direction, not a tested patch. The current follow-up call carrying inputResponses and requestState needs equivalent handling, and output validation, abort behavior, and retry semantics should remain intentional. Using native aggregated listTools() would also populate the SDK cache and retain its validation of header declarations.

The strict fixture above provides a regression test: a discovered modern tool with an x-mcp-header argument must send the matching Mcp-Param-* header and complete successfully. It currently fails with the latest TanStack release and passes with the native SDK.