[BUG] apm install writes bare ${VAR} in VS Code mcp.json headers

[kkadete]

Describe the bug

When a self-defined MCP server in apm.yml uses bare ${VARNAME} syntax in headers,
apm install writes those references verbatim into .vscode/mcp.json. The target "vscode", VS Code does not
resolve bare ${VARNAME} — it only understands ${env:VARNAME} (host environment) or
${input:id} (runtime prompt). The result is that the header value is sent as the literal
string ${VARNAME} to the MCP server instead of the secret value.

To Reproduce

Define a self-defined HTTP MCP server in apm.yml with a header using bare ${VAR} syntax:

   dependencies:
     mcp:
       - name: my-server
         registry: false
         transport: http
         url: https://my-server.example.com/mcp
         headers:
           Authorization: "Bearer ${MY_SECRET_TOKEN}"

Set MY_SECRET_TOKEN in the shell environment.
Run apm install.
Open .vscode/mcp.json — observe "Authorization": "Bearer ${MY_SECRET_TOKEN}" written verbatim.
Start the MCP server in VS Code — the header value is Bearer ${MY_SECRET_TOKEN} (literal string), not the token.

Expected behavior

apm install should translate bare ${VARNAME} references in headers to VS Code-compatible
${env:VARNAME} syntax before writing .vscode/mcp.json, so VS Code resolves them from the
host environment at runtime.

Expected output in .vscode/mcp.json:

"headers": {  "Authorization": "Bearer ${env:MY_SECRET_TOKEN}"}

Actual output:

"headers": {  "Authorization": "Bearer ${MY_SECRET_TOKEN}"}

Environment

OS: Windows 11
Python Version: 3.12
APM Version: 0.9.2

The target "copilot" should also take this into consideration, but removing the "env:" in case it exist.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/mcp-config
area/cli
type/bug
status/accepted
priority/high

Milestone

0.9.4

Suggested next action

In the VS Code MCP adapter, translate ${VARNAME} references in header values to ${env:VARNAME} before writing .vscode/mcp.json; also handle the Copilot target case (stripping env: if already present) noted in the issue.

Suggested issue comment

Thank you for this well-structured report -- the steps to reproduce, expected vs actual output, and environment details made the bug immediately clear.

This is confirmed. When `apm install` writes `.vscode/mcp.json` for MCP servers that use `${VARNAME}` syntax in `headers`, it must translate to VS Code's `${env:VARNAME}` format before writing. VS Code does not expand bare `${VARNAME}` at runtime, so the MCP server receives the literal string instead of the secret value.

The fix lives in the VS Code MCP adapter (look for `.vscode/mcp.json` write logic, likely under `src/apm_cli/adapters/` or `src/apm_cli/integration/`). The translation rule is: for each header value, replace `${VARNAME}` with `${env:VARNAME}`.

Your note about the Copilot target (stripping `env:` if it already exists) is also correct -- Copilot-style MCP config uses a different variable expansion format, so the translation should be target-aware. That can be tracked in the same PR.

This is tagged `priority/high` because users relying on environment-variable secrets in VS Code MCP server headers are silently getting the wrong behavior. A fix in 0.9.4 is appropriate.

If you would like to submit a PR for this, the fix scope is small and well-defined -- we would be happy to review it.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Clear bug with a well-understood user task: configure an MCP server with a secret API token in the header, install for VS Code target, and expect VS Code to resolve the token at runtime. The ${env:VARNAME} format is VS Code's documented syntax for host-environment resolution. apm install writing ${VARNAME} verbatim breaks the user's expectation silently -- the MCP server gets a literal string, not the secret. The fix is a target-aware variable-reference translation in the VS Code adapter.

Supply Chain Security Expert -- Risk-Surface Reviewer

Headers containing ${VARNAME} typically carry secrets (Bearer tokens, API keys). The bug causes VS Code to send the literal reference string to the MCP server rather than the resolved secret -- a data correctness issue, not a secret-exposure issue (the secret is never written to disk). The fix (translate to ${env:VARNAME}) is the correct approach: VS Code resolves from the host environment at runtime. No new security risk is introduced by the fix. area/mcp-config is the right area; theme/portability captures the VS Code-specific format gap.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author kkadete has NONE association -- first-time contributor. The bug report is excellent: minimal reproduction steps, expected vs actual output, environment details, and a concrete suggested fix direction. The reply is warm, acknowledges the quality of the report, and gives a concrete pointer to the fix location so the author can contribute a PR if they choose to.

Python Architect -- Architecture Reviewer

Not activated -- the bug is isolated to the VS Code MCP adapter's header-writing code path. No cross-cutting design decision is needed; the fix is a string transformation applied before writing .vscode/mcp.json. The Copilot target note adds a parallel case in the same adapter, which does not change the scope significantly.

Doc Writer -- Documentation Reviewer

Not activated -- the fix restores expected behavior implied by the VS Code MCP config spec; no new user-facing documentation pages are required. A future improvement to the MCP servers guide could note per-target variable expansion syntax, but that is not blocking.

APM CEO -- Triage Arbiter

Accepted and priority/high. Users configuring VS Code MCP servers with secret tokens in headers are silently broken -- VS Code sends the literal ${VARNAME} string. The fix is targeted, the reproduction is minimal, and this is exactly the kind of correctness bug that belongs in a patch. Welcome this first-time contributor's report warmly and make the fix location obvious in the reply. Milestone: 0.9.4.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/mcp-config", "area/cli"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "In the VS Code MCP adapter, translate ${VARNAME} references in header values to ${env:VARNAME} before writing .vscode/mcp.json; also handle the Copilot target case noted in the issue.",
  "comment_markdown": "Thank you for this well-structured report -- the steps to reproduce, expected vs actual output, and environment details made the bug immediately clear.\n\nThis is confirmed. When `apm install` writes `.vscode/mcp.json` for MCP servers that use `${VARNAME}` syntax in `headers`, it must translate to VS Code's `${env:VARNAME}` format before writing. VS Code does not expand bare `${VARNAME}` at runtime, so the MCP server receives the literal string instead of the secret value.\n\nThe fix lives in the VS Code MCP adapter (look for `.vscode/mcp.json` write logic, likely under `src/apm_cli/adapters/` or `src/apm_cli/integration/`). The translation rule is: for each header value, replace `${VARNAME}` with `${env:VARNAME}`.\n\nYour note about the Copilot target (stripping `env:` if it already exists) is also correct -- the translation should be target-aware. That can be tracked in the same PR.\n\nThis is tagged `priority/high` because users relying on environment-variable secrets in VS Code MCP server headers are silently getting the wrong behavior. A fix in 0.9.4 is appropriate.\n\nIf you would like to submit a PR for this, the fix scope is small and well-defined -- we would be happy to review it."
}

---

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 · ● 2.2M · ◷