[DOCS] MCP `headersHelper` docs missing per-server `CLAUDE_CODE_MCP_SERVER_NAME` and `CLAUDE_CODE_MCP_SERVER_URL` variables

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Use dynamic headers for custom authentication (headersHelper), with a matching update to the environment variables reference

Current Documentation

The MCP docs currently say:

If your MCP server uses an authentication scheme other than OAuth (such as Kerberos, short-lived tokens, or an internal SSO), use headersHelper to generate request headers at connection time. Claude Code runs the command and merges its output into the connection headers. Requirements: The command must write a JSON object of string key-value pairs to stdout The command runs in a shell with a 10-second timeout * Dynamic headers override any static headers with the same name The helper runs fresh on each connection (at session start and on reconnect). There is no caching, so your script is responsible for any token reuse.

The environment variables reference currently says:

Complete reference for environment variables that control Claude Code behavior. Claude Code supports the following environment variables to control its behavior. Set them in your shell before launching claude, or configure them in settings.json under the env key to apply them to every session or roll them out across your team.

It also includes other helper-related variables such as:

| CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS | Interval for refreshing dynamic OpenTelemetry headers (default: 1740000ms / 29 minutes) |

Neither page mentions CLAUDE_CODE_MCP_SERVER_NAME or CLAUDE_CODE_MCP_SERVER_URL.

What's Wrong or Missing?

Changelog v2.1.85 added CLAUDE_CODE_MCP_SERVER_NAME and CLAUDE_CODE_MCP_SERVER_URL for MCP headersHelper scripts so one helper can serve multiple servers, but the docs do not explain that this per-server context exists.

A. The headersHelper docs omit the new helper-script context

The MCP page explains how to configure headersHelper, what it must print, its timeout, and how often it runs, but it does not say that Claude Code now provides per-server environment variables when invoking the helper.

B. The authoritative environment variables reference does not list the new variables

Users searching the env-var reference for CLAUDE_CODE_MCP_SERVER_NAME or CLAUDE_CODE_MCP_SERVER_URL will not find them, so the changelog is currently the only discoverable source for this capability.

Suggested Improvement

Update the MCP page's headersHelper section to document that Claude Code sets CLAUDE_CODE_MCP_SERVER_NAME and CLAUDE_CODE_MCP_SERVER_URL before running the helper, explain what each variable contains, and show a short example of one helper script branching on server identity to emit different headers.

Also add entries for both variables to https://code.claude.com/docs/en/env-vars so they appear in the authoritative environment-variable reference.

For example, the MCP page could add a note like:

headersHelper scripts receive CLAUDE_CODE_MCP_SERVER_NAME and CLAUDE_CODE_MCP_SERVER_URL, so a single helper can generate different headers for different MCP servers.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Primary headersHelper documentation; should explain the new per-server environment variables and show how one helper can serve multiple servers |
| https://code.claude.com/docs/en/env-vars | Authoritative environment-variable reference; should list CLAUDE_CODE_MCP_SERVER_NAME and CLAUDE_CODE_MCP_SERVER_URL |

Total scope: 2 pages affected

Source: Changelog v2.1.85

Changelog entry: Added CLAUDE_CODE_MCP_SERVER_NAME and CLAUDE_CODE_MCP_SERVER_URL environment variables to MCP headersHelper scripts, allowing one helper to serve multiple servers