What
MCP servers are outside programs that give Claude extra tools. Several changes affect how Claude Code loads them when it runs headless, meaning without the interactive screen, as with -p or the SDK, or when it runs as a remote runner.
CLAUDE_CODE_REMOTE_MCP_CONFIGis a new environment variable. It points to a file holding the MCP servers a host delivered to the runner. Claude Code reads that file as a--mcp-configsource with the scopedynamicand a bridge session id, and only when a remote-session check passes.- The variable is added to the lists of variables that are passed on to child processes or protected, next to
CCR_SESSION_PROFILEandCLAUDE_RUNNER_ACTIVITY_FD. When Claude Code starts the child process, it builds the variable for it. - A delivered server whose name matches one of the operator's own
--mcp-configservers is refused asreserved_name. - If the variable did not reach the runner, a warning says that a later update of the delivered servers will shut down every
--mcp-configserver the update does not name. That includes the operator's own servers. - Several
--mcp-configsources are now collected into a list and go through an ownership and refusal step before they are merged. Refused servers are logged as warnings. Before, the sources were simply merged together. - The headless MCP refresh now filters servers by scope and by
strict-mcp-config, and logs how many configured servers it left out. Before, in some modes it applied every configured server except project and local ones. The same change adds amcpConfigOwnershipparameter, ajoinAlwaysLoadMcphook and a newpluginDiffScope. - When
joinAlwaysLoadMcpis provided, headless startup waits for always-load MCP servers before it goes on, and then uses the refreshed MCP state. - When a Remote Control
remote_tool_callrequest fails with status UNSPECIFIED, Claude is told not to retry and to carry on without the target.
Why
This changes which MCP servers end up loaded when Claude Code runs from scripts, the SDK or self-hosted runners. With strict-mcp-config set, a refresh should no longer pull in extra servers. A wrapper that does not pass CLAUDE_CODE_REMOTE_MCP_CONFIG on can lose its own --mcp-config servers, and the warning says so.
Names in the bundleCLAUDE_CODE_REMOTE_MCP_CONFIG--mcp-config
Documented inclaude-code/self-hosted-environments-configuration
Two sources agreeTwo things we can check say the same as this entry.
Anthropic's release notes agree
Fixed self-hosted runner sessions shutting down MCP servers added through an --exec-path wrapper's own --mcp-config when connectors change…
The name it cites is new in this build
New in this build: CLAUDE_CODE_REMOTE_MCP_CONFIG