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

Resolved 💬 6 comments Opened Feb 24, 2026 by mbu-ab Closed Apr 23, 2026

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"
    }
  }
}
  1. Restart Claude Code
  2. 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

View original on GitHub ↗

This issue has 6 comments on GitHub. Read the full discussion on GitHub ↗