MCP variable compatibility
apm.yml can reference environment variables in MCP env, args, command,
url and headers (see Variable references).
Every harness reads references differently, so APM renders them per harness.
This page records, for each supported harness, the native contract, what APM
writes, and the gaps that remain.
The results were checked on 2026-10-24 with the change for #3252; the Codex CLI rows were updated on 2026-11-12 for #3393. Evidence is marked as:
- client: checked against the native client.
- docs: taken from the harness’s official documentation only.
- unverified: the documentation does not say and no client was available.
A harness that is only documented or unverified is not counted as passing.
Native contract
Section titled “Native contract”| Harness (client checked) | APM writes to | Native syntax and fields | ${VAR:-default} |
Unset, no default | Approval before servers run | Evidence |
|---|---|---|---|---|---|---|
| Claude Code (2.1.310) | .mcp.json (project), ~/.claude.json (user) |
${VAR} in command, args, env, url, headers |
Supported | Left as literal text; claude mcp list warns |
Project servers need workspace trust and approval; user servers do not | client |
| GitHub Copilot CLI (1.0.44) | .github/mcp.json (project), ~/.copilot/mcp-config.json (user) |
${NAME} in command, args, env, header values (portable format) |
Supported (portable format) | Not documented | Project servers load only after folder trust | docs; client for file locations |
| VS Code | .vscode/mcp.json (project) |
${env:NAME}, ${input:id} in env, envFile, cwd, headers |
Only in the portable format | Not documented | Workspace servers follow Workspace Trust | docs |
| Cursor | .cursor/mcp.json (project), ~/.cursor/mcp.json (user) |
${env:NAME} in command, args, env, url, headers |
Not documented | Not documented | Tool calls ask for approval by default | docs |
| Codex CLI | .codex/config.toml (project), ~/.codex/config.toml (user) |
No interpolation. env_vars forwards variables; bearer_token_env_var and env_http_headers name variables for HTTP |
Not applicable | Not applicable | Project config only in trusted projects | docs |
| Gemini CLI | .gemini/settings.json (project), ~/.gemini/settings.json (user) |
$VAR or ${VAR} in env |
Not documented | Empty string | stdio servers connect only in trusted folders | docs |
| Antigravity | .agents/mcp_config.json (project), ~/.gemini/config/mcp_config.json (user) |
No interpolation documented; env is literal |
Not documented | Not documented | Tool calls run in Ask mode by default | docs |
| Hermes Agent | ~/.hermes/config.yaml (user) |
${VAR} documented for catalog entries (command, args, url, headers); config.yaml entries not documented |
Not documented | Not documented | enabled: false skips a server |
unverified |
| OpenCode | opencode.json (project), ~/.config/opencode/opencode.json (user) |
{env:VAR} in config values |
Not documented | Empty string | Not documented | docs |
| Windsurf | ~/.codeium/windsurf/mcp_config.json (user) |
${env:VAR} in command, args, env, serverUrl, url, headers |
Not documented | Empty string | Team allowlists only | docs (Cascade documentation) |
| Kiro | .kiro/settings/mcp.json (project), ~/.kiro/settings/mcp.json (user) |
${VAR} (documented in env and headers) |
Not documented | Not documented | Only variables listed in “Mcp Approved Env Vars” are expanded | docs |
| JetBrains Copilot | $XDG_CONFIG_HOME/github-copilot/intellij/mcp.json (user) |
Not documented | Not documented | Not documented | Not documented | unverified |
What APM writes
Section titled “What APM writes”For one self-defined stdio server and one self-defined HTTP server that use a
set variable (${DEMO_TOKEN}), a defaulted one (${DEMO_UNSET:-fallback}),
an unset one (${DEMO_MISSING}) and a static value (debug):
| Harness, scope | Set reference | Defaulted reference | Static value | Value written to the file? |
|---|---|---|---|---|
| Claude Code, project | ${DEMO_TOKEN} in every field |
Kept | Kept | No |
| Claude Code, user | env, headers: resolved at install time (unchanged); command, args, url copied |
Kept | Kept | Yes (file is 0o600, outside the repo) |
| Copilot CLI, project and user | ${DEMO_TOKEN} |
env: replaced by ${KEY}; other fields kept |
env: replaced by ${KEY} |
No |
| VS Code, project | env, headers: ${env:DEMO_TOKEN}; args: bare ${DEMO_TOKEN} |
Kept | Kept | No |
| Cursor, project and user | ${env:DEMO_TOKEN} in env, args, headers; command and url copied |
Kept | Kept | No |
| Codex CLI, project | env written as KEY: ${KEY}: env_vars = ["KEY"]; other env references and args: resolved; Authorization: bearer_token_env_var |
Kept | Kept | Only for references not written as KEY: ${KEY} |
| Codex CLI, user | env: resolved; Authorization: bearer_token_env_var |
Kept | Kept | Yes |
| Gemini CLI, project and user | Resolved at install time | Kept | Kept | Yes |
| Antigravity, project and user | Resolved at install time | Kept | Kept | Yes |
| Hermes Agent, user | Resolved at install time | Kept | Kept | Yes |
| OpenCode, project and user | {env:DEMO_TOKEN} in env, command, headers; url copied |
Kept as ${...} |
Kept | No |
| Windsurf, user | Resolved at install time | Kept | Kept | Yes |
| Kiro, project and user | ${DEMO_TOKEN} |
env: replaced by ${KEY} |
env: replaced by ${KEY} |
No |
| JetBrains Copilot, user | ${env:DEMO_TOKEN} |
env: replaced by ${env:KEY} |
env: replaced by ${env:KEY} |
No |
Known gaps
Section titled “Known gaps”These existed before #3252 and are recorded here rather than changed by it:
- Codex CLI user scope (and Codex project
envreferences not written asKEY: ${KEY}), Gemini CLI, Antigravity, Hermes Agent and Windsurf write the resolved value into their configuration. - Claude Code user scope resolves at install time although Claude Code
expands references in
~/.claude.jsontoo. - Targets that resolve at install time (Claude Code user scope, Codex CLI
user scope, Gemini CLI, Antigravity, Hermes Agent, Windsurf) resolve
envandheadersbut copy references incommand,argsandurlunchanged, including spellings such as${env:VAR}that the harness may not read. - Cursor and OpenCode copy references in
url(and Cursor incommand) unchanged. - Copilot CLI, Kiro and JetBrains Copilot replace static
envvalues and defaultedenvreferences with a reference named after the key. - VS Code leaves bare
${VAR}inargs, which the VS Code format does not expand. - Cursor, VS Code, OpenCode, Codex, Gemini CLI, Antigravity, Hermes Agent and
Windsurf copy
${VAR:-default}unchanged, although their documented syntax has no defaults. - Copilot CLI 1.0.44 reads project servers from
.mcp.jsononly, not the.github/mcp.jsonthat APM writes. Current GitHub documentation lists both. - Every harness: an MCP
urlmust start with a literalhttp://orhttps://, so the scheme itself cannot be a reference.
How this was checked
Section titled “How this was checked”- APM’s output: the same declarations were installed for every harness and scope with the installed CLI in an isolated home, using synthetic values, and each generated file and the CLI output were searched for those values.
- Claude Code: a project
.mcp.jsonand a user~/.claude.jsonusing${VAR},${VAR:-default}and an unset variable in every field were loaded by Claude Code 2.1.310 in an isolated configuration directory. A recording stdio command and a local HTTP endpoint captured the expanded values. - Copilot CLI:
copilot mcp list(1.0.44) in an isolated home showed which project files it reads.
Copyright (c) Microsoft Corporation. General documentation: CC-BY-4.0. Software, code examples and OpenAPM: Apache-2.0. See scope and exclusions.