[DOCS] MCP docs omit remote-header env-var expansion coverage for SSE/WebSocket

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:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Main 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:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/agent-sdk/mcp | Shows ${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