[BUG] Self-defined stdio MCP env ${VAR} placeholders written verbatim instead of resolved at install time (Codex/Claude)

[cffnpwr]

Describe the bug

When a self-defined stdio MCP server (registry: false, transport: stdio) declares a ${VAR} placeholder in its env block, targets that resolve variables at install time (Codex, Claude) write the placeholder string verbatim into the target config — even when the real value is present in os.environ. The MCP child process then receives an unresolved string like MY_TOKEN=${MY_TOKEN} and fails authentication.

On the same target, HTTP server header values resolve correctly. The problem is limited to the self-defined stdio env block.

To Reproduce

Requirements: apm v0.23.0.

1. Create a directory with the following apm.yml, and create .claude/ as the Claude target signal:

name: repro
version: 1.0.0
dependencies:
  mcp:
    - name: env-demo
      registry: false
      transport: stdio
      command: echo
      args: ["noop"]
      env:
        MY_TOKEN: "${MY_TOKEN}"

2. Install with the real value in the environment:

MY_TOKEN="repro-secret-not-a-real-token" apm install --target claude

3. Inspect the generated .mcp.json:

cat .mcp.json

Codex behaves the same (project scope writes to .codex/config.toml):

MY_TOKEN="repro-secret-not-a-real-token" apm install --target codex
cat .codex/config.toml

Expected behavior

docs/.../reference/manifest-schema.md §4.2.4 "Variable References in headers and env" normatively specifies install-time os.environ resolution for targets without runtime interpolation:

Codex, Gemini, and Cursor have no runtime interpolation, so APM resolves ${VAR}, ${env:VAR}, and the legacy <VAR> at install time using os.environ (or an interactive prompt when missing).

The same table's ${VAR} row (Codex/Gemini/Cursor column) also states "Resolved at install time from env (or interactive prompt)".

Claude is not in that table, but src/apm_cli/adapters/client/claude.py requires the same behaviour:

# Claude Desktop / Code's mcp config does NOT support runtime env-var
# substitution -- the value in ``env`` must be a literal string. This
# adapter MUST keep the legacy install-time resolution behaviour.
_supports_runtime_env_substitution: bool = False

So env: { MY_TOKEN: "${MY_TOKEN}" } should be written resolved to the real value of os.environ["MY_TOKEN"].

Actual behavior

Claude .mcp.json — MY_TOKEN is unresolved:

{
  "mcpServers": {
    "env-demo": {
      "type": "stdio",
      "command": "echo",
      "env": { "MY_TOKEN": "${MY_TOKEN}" },
      "args": ["noop"]
    }
  }
}

Codex .codex/config.toml — identical:

[mcp_servers.env-demo.env]
MY_TOKEN = "${MY_TOKEN}"

For contrast, on the same Claude target, writing the value into an HTTP server header as "Authorization": "Bearer ${MY_TOKEN}" resolves correctly ("Bearer repro-secret-not-a-real-token"). This difference between the stdio env block and the header narrows down the cause.

Environment

• OS: macOS 26.5.1
• Python Version: runs on APM's bundled Python 3.12 build (Homebrew)
• APM Version: 0.23.0 (01b337f)
• Affected targets: codex, claude

Additional context

Likely cause: for the self-defined stdio env block, the same dep.env dict is passed into the resolution pipeline as both the values to resolve and the env_overrides map. The lookup env_overrides.get(name) or os.getenv(name) then returns the placeholder string (truthy) and never reaches os.getenv, so ${MY_TOKEN} "resolves" to itself. Header values are not keys in that map, so they fall through to os.getenv and resolve correctly — matching the contrast above. I can add a file/line walkthrough and a note on the test gap in a comment.

Not a duplicate

• [BUG] Claude .mcp.json drops env for self-defined stdio MCP servers #1222 — Claude .mcp.json drops env for self-defined stdio MCP servers (the env block was emitted empty; that path now carries the env).
• [BUG] Codex and Gemini adapters pass self-defined stdio env verbatim, skipping placeholder resolution #1266 — Codex/Gemini passed self-defined stdio env verbatim by not routing it through the resolver; that was fixed by wiring the env block through _resolve_environment_variables. This report is the next layer: the env block now reaches the resolver, but the resolver shadows os.environ with the placeholder dict, so the value is still not resolved (and the [BUG] Codex and Gemini adapters pass self-defined stdio env verbatim, skipping placeholder resolution #1266 fix is what now routes Codex through that shadowing path).

[cffnpwr]

Root cause walkthrough

For the self-defined stdio env block, the same dep.env is passed into the resolution pipeline as both the values to resolve (env_vars) and the override map (env_overrides):

• mcp_integrator_install.py:546 — self_defined_env = dep.env or {} ({"MY_TOKEN": "${MY_TOKEN}"})
• mcp_integrator_install.py:570 — passes self_defined_env as shared_env_vars into _install_for_runtime
• operations.py:84 — passes it as env_overrides=shared_env_vars into install_servers
• During resolution, each value of env_vars (= raw["env"] = dep.env) is resolved using env_overrides (= dep.env, the same dict):
  • Codex: base.py:577 (via the "legacy mode, dict shape (self-defined stdio)" branch at base.py:493)
  • Claude: copilot.py:811

In both cases the relevant line is:

env_value = env_overrides.get(env_name) or os.getenv(env_name)

env_overrides.get("MY_TOKEN") returns the placeholder string "${MY_TOKEN}" (truthy), so or os.getenv(...) is never reached and the placeholder "resolves" to itself. Header values are not keys in env_overrides, so they fall through to os.getenv and resolve correctly — the difference shown by the header contrast in the issue.

Test gap

• test_mcp_env_var_copilot_e2e.py TestMcpEnvVarHeadersCursor::test_cursor_still_resolves_env_vars_to_literal is the only nearby test covering legacy resolve-to-literal mode, but it uses an HTTP header, so it never exercises the shadowing path and cannot catch this bug.
• There is no test that resolves a self-defined stdio env block in legacy mode and asserts the literal value is written.

[github-actions]

Triage decision

accept

Proposed labels

theme/security
area/mcp-config
area/content-security
type/bug
status/accepted

Milestone

null

Suggested next action

Fix the env-var resolution path for self-defined stdio MCP servers: do not pass dep.env as env_overrides; fall through to os.getenv for ${VAR} resolution as documented in manifest schema section 4.2.4 (affects claude and codex adapters at minimum).

Suggested issue comment

Thanks for this excellent bug report -- the reproduction steps, the contrast with working header resolution, the root cause analysis, and the distinctions from #1222 and #1266 make this immediately actionable.

The bug is confirmed: for self-defined stdio MCP servers, `${VAR}` in the `env` block is written verbatim because `dep.env` is passed as both the source values and the `env_overrides` map. The `env_overrides.get(name)` lookup returns the placeholder string (truthy), so `os.getenv` is never reached. Headers resolve correctly because they are not keys in that map, which confirms the root cause.

The fix is targeted: the self-defined stdio env resolution path must not use `dep.env` as `env_overrides`; it should fall through to `os.getenv` (or an interactive prompt when the env var is absent) per the documented behavior in manifest schema section 4.2.4.

Note: no active milestone is currently visible in the tracker. A maintainer should assign this to an upcoming patch -- this is a silent auth failure and warrants priority attention.

If you can share the specific file and function pointer from your walkthrough (you mentioned you could add one), that would help reviewers land the fix faster.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

High-quality bug report with a clear user impact: self-defined stdio MCP servers that need auth credentials via env vars silently fail when installed to Claude or Codex. The user cited the manifest schema documentation as the source of expected behavior and provided a working contrast (headers resolve correctly). The failure mode is invisible at install time (no error, no warning), which makes it especially harmful. This meets the "failure mode is the product" bar by providing reproduction steps and a root cause hypothesis.

Supply Chain Security Expert -- Risk-Surface Reviewer

This bug is in the credential delivery path for Claude and Codex MCP adapters. The current behavior causes auth failure (token not delivered), not credential exposure -- risk direction is availability, not confidentiality. However, the code path (env_overrides shadowing os.getenv) is within the P/G/S surface for token handling. The fix must ensure: (1) the resolved token is written only to the local MCP config, not logs or error output; (2) the fix does not introduce a regression where legitimate env_overrides from a different source (e.g. policy-injected) are silently dropped. theme/security + area/content-security are warranted because this is credential resolution failure in the MCP auth delivery chain.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author association is NONE and the report quality is exceptional -- root cause, reproduction, doc citations, and prior-issue distinctions. The reply should open with specific appreciation for the report quality, confirm the bug explicitly, and close with an invitation to share the file/line walkthrough they mentioned. This is a strong conversion moment: a new contributor doing high-quality bug archaeology is exactly the profile to nurture.

Python Architect -- Architecture Reviewer

Not activated -- the root cause is clearly identified and the fix path is targeted (do not pass dep.env as env_overrides in the self-defined stdio env resolution path). No cross-cutting design decision is required; the fix is local to the adapter resolution logic in the Claude and Codex adapter classes.

Doc Writer -- Documentation Reviewer

Not activated -- the documentation at manifest schema section 4.2.4 already correctly describes the expected behavior (${VAR} resolved from os.environ at install time). No doc changes are needed; the bug is in the implementation, not the spec.

APM CEO -- Triage Arbiter

Well-researched, reproducible bug with clear root cause and direct user impact. The author has done more diagnostic work than most reporters and explicitly distinguished this from two prior related fixes. theme/security is correct because this is in the credential delivery path for MCP configs. No active milestone is visible (open milestones 0.14.0 and 0.20.0 appear stale against the current v0.23.1 release); a maintainer should assign to an upcoming patch and apply priority/high. Accepted.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/security",
  "areas": ["area/mcp-config", "area/content-security"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Fix the env-var resolution path for self-defined stdio MCP servers: do not pass dep.env as env_overrides; fall through to os.getenv for ${VAR} resolution per manifest schema section 4.2.4.",
  "comment_markdown": "Bug confirmed: dep.env is passed as both source values and env_overrides, causing ${VAR} to resolve to itself. Fix is targeted to the stdio env resolution path in the Claude and Codex adapters. Maintainer should assign to an upcoming patch with priority/high."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · 167.1 AIC · ⌖ 24.4 AIC · ⊞ 9.2K · ◷