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

Activity

1. mintuhouse

   added a commit that references this issue on Oct 15, 2026

   Fix GitHub MCP support while retaining TanStack (#304)

   ...

   5a1448f
2. github-actions

   assigned

   tombeckenham

   on Oct 15, 2026
3. github-actions

   added

   waiting-on: maintainerThe ball is in the maintainers’ courtThe ball is in the maintainers’ court

   on Oct 15, 2026
4. kyleromines commented on Oct 21, 2026

   

   kyleromines

   on Oct 21, 2026

   Last edited by kyleromines

   More actions

   @tombeckenham
   Still reproduces on 0.9.2 (published 2026-10-21): packages/ai-mcp/src is identical to 0.9.0, and dist/esm/tools.js still calls transport.send() with no options on the modern tools/call path.

   We hit this against GitHub's MCP server as:

   ProtocolError: header mismatch: missing Mcp-Param-repo header for parameter "repo"
   

   Here is a self-contained repro that needs no GitHub and no fake fetch. It uses only the official SDK server, which enforces SEP-2243 itself.

   Versions: @tanstack/ai-mcp 0.9.2, @modelcontextprotocol/client 2.2.0, @modelcontextprotocol/server 2.2.0, zod 4.6.7, Node 22.22.0.

   // repro.mjs — npm i @tanstack/ai-mcp@0.9.2 @tanstack/ai @modelcontextprotocol/client@2.2.0 @modelcontextprotocol/server@2.2.0 zod
   import { createServer } from 'node:http'
   import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
   import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'
   import { createMCPClient } from '@tanstack/ai-mcp'
   import { z } from 'zod'
   
   // A 2026-07-28-only server whose `repo` argument is mirrored into Mcp-Param-Repo.
   const build = () => {
     const server = new McpServer({ name: 'repro', version: '1.0.0' })
     server.registerTool(
       'get_repo',
       {
         description: 'Echoes the repo.',
         inputSchema: z.object({ repo: z.string().meta({ 'x-mcp-header': 'Repo' }) }),
       },
       ({ repo }) => ({ content: [{ type: 'text', text: `got ${repo}` }] }),
     )
     return server
   }
   const handler = createMcpHandler(build, { legacy: 'reject' })
   
   const seen = []
   const http = createServer(async (req, res) => {
     const chunks = []
     for await (const chunk of req) chunks.push(chunk)
     const body = Buffer.concat(chunks)
     const headers = new Headers()
     for (const [k, v] of Object.entries(req.headers)) if (typeof v === 'string') headers.set(k, v)
     if (req.method === 'POST' && body.includes('"tools/call"')) {
       seen.push(Object.fromEntries([...headers].filter(([k]) => k.startsWith('mcp-param-'))))
     }
     const response = await handler.fetch(
       new Request(`http://127.0.0.1${req.url}`, {
         method: req.method,
         headers,
         body: req.method === 'GET' || req.method === 'HEAD' ? undefined : body,
       }),
     )
     res.writeHead(response.status, Object.fromEntries(response.headers))
     if (!response.body) return res.end()
     for await (const chunk of response.body) res.write(chunk)
     res.end()
   })
   await new Promise((r) => http.listen(0, '127.0.0.1', r))
   const url = `http://127.0.0.1:${http.address().port}/mcp`
   
   // 1. The SDK's own client.
   const sdk = new Client({ name: 'sdk', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } })
   await sdk.connect(new StreamableHTTPClientTransport(new URL(url)))
   console.log('SDK era:', sdk.getProtocolEra())
   const direct = await sdk.callTool({ name: 'get_repo', arguments: { repo: 'octo/hello' } })
   console.log('SDK Client.callTool:', JSON.stringify(direct.content), 'Mcp-Param headers sent:', JSON.stringify(seen.at(-1)))
   await sdk.close()
   
   // 2. @tanstack/ai-mcp.
   const mcp = await createMCPClient({ transport: { type: 'http', url } })
   const tool = (await mcp.tools()).find((t) => t.name === 'get_repo')
   try {
     console.log('ai-mcp:', JSON.stringify(await tool.execute({ repo: 'octo/hello' })))
   } catch (error) {
     console.log('ai-mcp threw:', error.constructor.name, error.code, error.message)
   } finally {
     console.log('ai-mcp Mcp-Param headers sent:', JSON.stringify(seen.at(-1)))
     await mcp.close()
     http.closeAllConnections()
     http.close()
   }

   Output:

   SDK era: modern
   SDK Client.callTool: [{"type":"text","text":"got octo/hello"}] Mcp-Param headers sent: {"mcp-param-repo":"octo/hello"}
   ai-mcp threw: ProtocolError -32020 Bad Request: the request headers and body disagree: the body carries repo="octo/hello" but the Mcp-Param-Repo header is absent
   ai-mcp Mcp-Param headers sent: {}
   

   A few details that may help with the fix:

   1. Both raw call sites miss the header. callMcpTool uses rawRequest for the first modern tools/call and again for the retry after an input_required result, so a fix needs to cover both.
   2. The raw path also loses the SDK's recovery. Client.callTool recovers from a -32020: it evicts the cached tool definition, re-lists, and retries once. You can see this in the repro if you log requests. The SDK's first call goes out with no header because nothing is cached yet, is refused, and is retried after a tools/list. The raw path has neither the header nor the retry. ai-mcp had already listed the tools in the repro, so it had the schema and still sent no header.
   3. The transport already supports per-request headers. StreamableHTTPClientTransport.send(message, { headers }) merges them into the request and skips reserved names. Passing the Mcp-Param-* headers built from the listed tool's inputSchema would be enough. The catch is that the SDK's builder (scanXMcpHeaderDeclarations / buildMcpParamHeaders, including the =?base64?…?= encoding for non-ASCII values) isn't exported from @modelcontextprotocol/client. So the options are routing through callTool, as suggested above, asking the SDK to export the builder, or copying its rules.
5. tombeckenham

   added a commit that references this issue on Oct 22, 2026

   fix(ai-mcp): send Mcp-Param headers on spec 2026 tool calls

   ...

   This issue will close once commit 52732c8 is merged into the 'main' branch.

   52732c8
6. tombeckenham

   linked a pull request that will close this issuefix(ai-mcp): send Mcp-Param headers on spec 2026 tool calls #1871on Oct 22, 2026
7. AlemTuzlak

   added a commit that references this issue on Oct 22, 2026

   fix(ai-mcp): send Mcp-Param headers on spec 2026 tool calls (#1871)

   ...

   This issue will close once commit d980ce1 is merged into the 'main' branch.

   d980ce1
8. AlemTuzlak

   closed this as completedin #1871on Oct 22, 2026