Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesiTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Claude Code’s documented `.mcp.json` expansion supports `${VAR}` and `${VAR:-default}` in five fields: `command`, `args`, `env`, `url` and `headers`. A report testing Claude Code 2.1.278 on macOS found that bare `$VAR` stayed literal, nested defaults behaved differently by field, and headers appeared to get an extra expansion pass. That last behavior is undocumented, so use only the two documented forms.
What does Claude Code officially support in `.mcp.json`?
Anthropic’s Claude Code MCP reference says environment-variable expansion is supported in `.mcp.json` using two forms:
![Claude AI for Beginners Bible: [5 in 1] The Ultimate Guide to Automate Your Work, Save Hours Every Week, and Use AI for Real-World Results](https://m.media-amazon.com/images/I/415+fSJacsL._SL160_.jpg)
${VAR}expands to the environment variable’s value.${VAR:-default}uses the variable’s value when it is set, or the supplied default when it is unset.
The documented fields are command (server executable), args (command-line arguments), env (environment passed to the server), url (HTTP server URL) and headers (HTTP request headers). The reference does not document bare-dollar expansion, nested defaults or a second expansion pass.
Recommended Free Tools
What happens when a referenced variable is unset?
For an ordinary unset variable without a default, the reference says configuration still loads, Claude Code warns in claude mcp list, and the ${VAR} text remains unexpanded. This differs from a variable with a default, which is intended to resolve to that default.
#1 Best Overall
Why can a remote header ignore a credential variable?
Anthropic documents special handling for certain credential-like names in remote url and headers. Those variables are read as empty whether set or unset, and a :-default fallback is ignored. Listed examples include ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY and NPM_TOKEN. If a remote server needs such a value, the documentation says to copy it to a differently named variable and use that variable instead.
What about CLAUDE_PROJECT_DIR?
Anthropic notes that CLAUDE_PROJECT_DIR is set in the spawned server’s environment, not Claude Code’s environment. As a result, using it for expansion in project-level command or args may require a default such as ${CLAUDE_PROJECT_DIR:-.}. Alternatively, the server can read the variable from its own process environment.
Does Claude Code expand bare $VAR?
Not in the tested cases reported by Rulestack. Its September 28, 2026 report, edited October 3, says bare $PROBE_SET remained literal in the tested fields; a bare-dollar form in command failed to launch. This was not shell expansion: the report describes the value being passed as text.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWhat did the six-form test find?
The report describes Claude Code 2.1.278 on macOS, with Node v22.22.2. The author used a small stdio server to record arguments and environment, plus a separate HTTP server to log requests and headers. The author reports that the spawn log and the echo_env tool result agreed byte for byte.
The table separates documented behavior from outcomes attributed to that one test. “Tested cases” means the report’s particular setup and fields, not a guarantee for all configurations or releases.
| Form or case | Documented contract | Rulestack report: Claude Code 2.1.278 on macOS |
|---|---|---|
${PROBE_SET}, with variable set |
Expands to the variable’s value in the five documented fields. | Expanded to the set value in tested args and env cases. |
${PROBE_UNSET:-fallback}, with variable unset |
Uses the provided default. | Expanded to the fallback in tested args, env, url and headers cases. |
${PROBE_SET:-fallback}, with variable set |
Uses the variable’s value rather than the default. | Expanded to the set value. |
$PROBE_SET |
Not listed as a supported expansion form. | Remained literal in tested fields; the command case failed to launch. |
${PROBE_UNSET}, with variable unset and no default |
Remains unexpanded, with a warning in claude mcp list. |
Remained literal in the reported test. |
${PROBE_UNSET:-${PROBE_SET}} |
Nested defaults are not described in the reference. | Was partly literal in command, args, env and url; in headers, it resolved to the set value. |
Can `.mcp.json` use nested variable defaults?
The test does not support treating nested defaults as reliable across fields. In the report’s setup, ${PROBE_UNSET:-${PROBE_SET}} was partly literal in command, args, env and url. Although it resolved in headers, Anthropic does not document nested-default syntax. Prefer a simple variable reference or a single default rather than nesting expansions.
Rank #4
Why did an MCP header behave differently from `args`?
Rulestack also reports that a header whose value was itself ${PROBE_SET} resolved to the inner value. Together with the nested-default result, this led the author to infer that headers received a second expansion pass. That is an interpretation of the reported observations, not an Anthropic-documented feature. Do not depend on repeated header expansion: behavior outside the documented forms may change.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →The report’s credential probe also found that NPM_TOKEN and a fallback form using that name arrived as empty header values, consistent with Anthropic’s documented credential handling. This is distinct from the ordinary unset-variable case: protected credential-like names in remote headers are treated as empty even when a fallback is supplied.
What should you use in a real MCP configuration?
- Use
${VAR}when the variable should be set in the environment available to Claude Code. - Use
${VAR:-default}when a deliberate fallback is appropriate. - Use these documented forms in
command,args,env,urlandheaders; do not substitute bare$VAR. - For a remote URL or header, do not expect a protected credential-like name or its fallback to supply a value. Use a differently named copy if the remote service requires it.
- For project paths, account for
CLAUDE_PROJECT_DIRbeing available to the spawned server rather than Claude Code’s own expansion environment.
The MCP documentation describes MCP as an open-source standard for connecting AI applications to external systems, including data sources, tools and workflows. That broader context does not change the `.mcp.json` expansion rules.
How broadly do the reported results apply?
The observations are a single author-reported test of Claude Code 2.1.278 on macOS with Node v22.22.2. The cited sources do not establish that the same results hold on other Claude Code releases, operating systems or configurations. Anthropic’s documentation is the appropriate basis for a portable configuration; the reported extra behavior, especially the apparent header pass, should be treated as version-specific observation rather than a supported contract.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
