Custom headers from .mcp.json not forwarded on MCP tool call POST requests

[mbu-ab]

Description

Custom headers defined in .mcp.json for remote MCP servers are not forwarded when Claude Code makes tool call POST requests. The headers may be sent on the initial SSE connection, but they are not included on subsequent /messages POST requests used for actual tool invocations.

Steps to Reproduce

1. Configure a remote MCP server in ~/.claude/.mcp.json with custom headers:

{
  "my-server": {
    "type": "sse",
    "url": "https://example.com/mcp/sse",
    "headers": {
      "X-API-KEY": "valid-api-key"
    }
  }
}

2. Restart Claude Code
3. Invoke any tool from that MCP server

Expected behavior

The X-API-KEY header should be included in the POST request to /mcp/messages when calling tools.

Actual behavior

The server receives no X-API-KEY header on tool call POSTs, resulting in authentication failure.

Evidence that the header is the issue (not the key or server)

Direct curl to the same endpoint with the same header succeeds:

curl -s -w "\nHTTP_CODE: %{http_code}" \
  -H "X-API-KEY: <key>" \
  -X POST "https://example.com/mcp/messages" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"who_am_i","arguments":{}}}'
# Returns HTTP 200

The same call through Claude Code fails with an authentication error from the server.

Additional context

• Tested with both "type": "sse" and "type": "streamable-http" — same behavior
• Confirmed no stale OAuth entries in ~/.claude/.credentials.json interfering
• The server (Ruby/Rails with fast-mcp gem) expects the API key as a custom header, not via OAuth
• Claude Code also auto-discovers OAuth endpoints on the server and can create stale OAuth entries in .credentials.json with empty access tokens — this is a separate but related issue that compounds the problem

Environment

• macOS (Darwin 25.3.0)
• Claude Code CLI (latest)
• MCP server: fast-mcp 1.6.0 (Ruby) with SSE transport

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] HTTP MCP server custom headers not being sent to server #14976
2. [BUG] HTTP MCP server custom headers not being sent to server #14977
3. [BUG] MCP headers with environment variable substitution not being sent from .mcp.json #6204

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[mbu-ab]

Workaround Found

Using claude mcp add with -s user scope (which stores config in ~/.claude.json) instead of manually editing ~/.claude/.mcp.json does correctly forward custom headers on tool call POST requests.

claude mcp add my-server "https://example.com/mcp/sse" \
  -t sse -s user \
  -H "X-API-KEY: my-key"

This stores the server config in ~/.claude.json (user scope = global across all projects). Headers defined this way are forwarded correctly on SSE tool call POSTs.

Summary: The bug is specific to headers defined in ~/.claude/.mcp.json — they are not forwarded. The same headers defined via claude mcp add (stored in ~/.claude.json) work fine.

[mbu-ab]

Checked for duplicates — the closest match is #17069 ("[BUG] MCP header not added in ~/.claude.json"), but that was about claude mcp add not saving headers to the config file (CLI bug, now closed/fixed). This issue is different: headers defined in .mcp.json are saved correctly but not forwarded on tool call POST requests at runtime.

[ralphkrauss]

[Claude Code]: We're hitting this as well on v2.1.83 (Windows 11). Our .mcp.json configures an HTTP MCP server (Aspire Dashboard) with a custom x-mcp-api-key header — no OAuth involved. Claude Code ignores the headers field and tries OAuth, which fails with HTTP 403: Invalid OAuth error response: SyntaxError: JSON Parse error: Unexpected EOF.

The same config added via claude mcp add -t http -s local -H "x-mcp-api-key: ..." to ~/.claude.json works correctly — headers are sent and the server connects fine. So the issue is specific to headers loaded from .mcp.json.

This started breaking around v2.1.74 (per #33817). Previously worked without issues.