Streamable HTTP MCP: headers and headersHelper not sent with requests

[hweissta]

Bug Description

When using a Streamable HTTP MCP server ("type": "http") with either headers or headersHelper in .mcp.json, Claude Code does not attach the configured headers to the HTTP requests it sends to the MCP endpoint.

Reproduction

.mcp.json config (tried both variants):

With headersHelper:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://example.com/api/v4.0/mcp",
      "headersHelper": "./get-token.sh"
    }
  }
}

With static headers:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://example.com/api/v4.0/mcp",
      "headers": {
        "Authorization": "Bearer <valid-token>"
      }
    }
  }
}

Steps to reproduce:

1. Configure an HTTP MCP server that requires Bearer token auth (validated at the gateway before reaching the MCP handler)
2. Run /mcp to connect
3. Call any tool

Expected behavior:

The Authorization header from headers/headersHelper should be included in every HTTP POST to the MCP endpoint.

Actual behavior:

The request reaches the server without the Authorization header, resulting in a 403 from the auth gateway.

Verification:

• The same token works when calling the endpoint directly via curl or Postman
• The headersHelper script produces valid output: {"Authorization": "Bearer eyJ..."}
• Server-side logs confirm the request never reaches the MCP handler (blocked at the auth gateway layer)
• Both headers and headersHelper configurations exhibit the same behavior

Environment

• macOS (Darwin 24.6.0)
• Claude Code CLI

🤖 Generated with Claude Code

[github-actions]

Found 3 possible duplicate issues:

1. Custom headers from .mcp.json not forwarded on MCP tool call POST requests #28293
2. headersHelper silently ignored since v2.1.85 — Claude Code skips to OAuth discovery instead #44774
3. [Bug] MCP Server Authorization Header Not Recognized, Falls Back to OAuth #33817

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

[0xbrainkid]

Headers not being forwarded for Streamable HTTP MCP is a significant auth regression — the entire point of headers/headersHelper is to attach bearer tokens or API keys, and silently dropping them means the MCP server receives unauthenticated requests that either fail or (worse) succeed with anonymous access depending on the server configuration.

The headersHelper case is particularly concerning from a security perspective: if the script runs but its output is not attached to requests, operators may assume authentication is working when it is not. Silent auth failure in an MCP context means tool calls proceed without the intended authorization scope — an agent may be invoking privileged tools with anonymous-level access.

From an agent identity perspective, this also matters for MCP servers that use the Authorization header to identify the calling agent (not just authenticate it). An MCP server that expects Authorization: Bearer <agent-specific-token> as a way to scope tool access per-agent cannot enforce that scoping if Claude Code drops the header. The agent identity that the server was expecting to gate access on is never presented.

Practical workaround while the fix is in progress: for headersHelper, verify the script is executable and outputs valid JSON, then check Claude Code logs for whether the script is being invoked. For static headers, confirm the key names are lowercase (HTTP/2 requires lowercase headers and some implementations silently drop uppercase ones).

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.