Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] MCP docs omit remote-header env-var expansion coverage for SSE/WebSocket [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#52619•Fetched 2026-04-24 06:02:17
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×3

Code Example

{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}
RAW_BUFFERClick to expand / collapse

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

Environment variable expansion in .mcp.json for remote-server headers

Current Documentation

The docs currently say:

Expansion locations: Environment variables can be expanded in:

  • command - The server executable path
  • args - Command-line arguments
  • env - Environment variables passed to the server
  • url - For HTTP server types
  • headers - For HTTP server authentication

And the example only shows an HTTP server:

{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}

Later on the same page, the policy section says:

Remote servers (HTTP, SSE, WebSocket) use URL-based matching when serverUrl entries exist in the allowlist

What's Wrong or Missing?

Changelog v2.1.119 fixed ${ENV_VAR} placeholders in MCP request headers for HTTP, SSE, and WebSocket servers before requests are sent.

The current MCP page only describes header expansion as HTTP-specific and only shows an HTTP example. It does not tell users that the same ${VAR} placeholder behavior applies to other remote MCP transports that send headers, especially SSE and WebSocket.

That leaves a documentation gap for users configuring authenticated remote MCP servers outside the basic HTTP example. They have to infer whether header placeholders are supported for SSE/WebSocket at all, and whether those values are resolved before the initial request/connection.

Suggested Improvement

Update https://code.claude.com/docs/en/mcp to make remote-header placeholder behavior explicit:

  • In the .mcp.json environment-variable expansion section, change the headers bullet from HTTP-only wording to wording that covers remote MCP transports that accept headers (HTTP, SSE, and WebSocket).
  • Add a short note that ${VAR} and ${VAR:-default} placeholders in headers are resolved before the outbound request/connection is made.
  • Add one non-HTTP example (SSE or WebSocket) showing a header such as "Authorization": "Bearer ${API_TOKEN}".

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageContext
https://code.claude.com/docs/en/mcpMain MCP configuration page; header expansion is documented with HTTP-only wording even though the product change in v2.1.119 covers HTTP/SSE/WebSocket request headers

Total scope: 1 page directly affected

Agent SDK cross-reference:

PageContext
https://code.claude.com/docs/en/agent-sdk/mcpShows ${API_TOKEN} in remote-server headers for HTTP/SSE, which is useful consistency context when updating the main MCP page

Source: Changelog v2.1.119

Exact changelog entry: Fixed ${ENV_VAR} placeholders in headers for HTTP/SSE/WebSocket MCP servers not being substituted before requests

extent analysis

TL;DR

Update the MCP documentation to explicitly state that environment variable placeholders in headers are supported for HTTP, SSE, and WebSocket remote servers and are resolved before the outbound request/connection is made.

Guidance

  • Review the current documentation at https://code.claude.com/docs/en/mcp and identify the sections that need to be updated to reflect the correct behavior of environment variable placeholders in headers for non-HTTP remote servers.
  • Update the .mcp.json environment-variable expansion section to include wording that covers remote MCP transports that accept headers (HTTP, SSE, and WebSocket).
  • Add a note to clarify that ${VAR} and ${VAR:-default} placeholders in headers are resolved before the outbound request/connection is made.
  • Consider adding a non-HTTP example (SSE or WebSocket) to demonstrate the usage of environment variable placeholders in headers.

Example

{
  "mcpServers": {
    "sse-server": {
      "type": "sse",
      "url": "${SSE_BASE_URL:-https://sse.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${SSE_API_TOKEN}"
      }
    }
  }
}

Notes

The update should ensure consistency with the Agent SDK documentation at https://code.claude.com/docs/en/agent-sdk/mcp, which already shows environment variable placeholders in remote-server headers for HTTP/SSE.

Recommendation

Apply workaround by updating the documentation as suggested to ensure clarity and consistency for users configuring authenticated remote MCP servers.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#indexing error#inference speed#output truncation#environment variable

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] MCP docs omit remote-header env-var expansion coverage for SSE/WebSocket [1 participants]