Env placeholder syntax for --header/--env is undiscoverable from CLI or npm package; ${env:VAR} silently passes through verbatim

[elecnix]

Summary

The environment placeholder format supported by mcporter for HTTP headers and stdio env values (${VAR}, ${VAR:-fallback}, and whole-value $env:VAR) is not discoverable by a user or coding agent that only has the npm package installed: it is not mentioned in any --help text, the README only says configs accept "environment placeholders" without giving the syntax, and the docs that do document it (docs/config.md) are not shipped in the published package (the tarball contains only dist/, LICENSE, README.md, and package.json). The only way to learn the format without opening the repo on GitHub is to read dist/env.js / dist/runtime/utils.js in the installed package.

Worse, the ${env:VAR} syntax that is the de-facto convention in Cursor / Claude Code / Codex / Windsurf MCP configs is silently NOT expanded: a header value like Authorization: Bearer ${env:SOME_API_KEY} is sent over the wire literally, producing a 401 that looks like a wrong API key. I hit exactly this: mcporter config add <name> <url> --header "Authorization=Bearer ${env:INNGEST_API_KEY}" wrote the config fine and connected with 401; switching the config to ${INNGEST_API_KEY} worked immediately. The placeholder regex requires an identifier followed by } or :-fallback, so ${env:VAR} fails the match and falls through untouched, and materializeHeaders sends the literal string. Because the CLI help promises nothing about interpolation, a user has no way to know this is the cause.

Places where the format could be mentioned (so a user or agent knows without reading source)

1. mcporter config add --help — the --header KEY=value and --env KEY=value flag descriptions should state the supported placeholders and show an example, since that is the exact moment a user is authoring header/env values.
2. mcporter config --help and mcporter config get --help — parent/subcommand help for the config surface.
3. README.md — the sentence "Config files accept JSONC, environment placeholders, ..." should include the syntax inline (at minimum ${VAR} / ${VAR:-fallback} / $env:VAR), because docs/config.md is not available to npm installers.
4. The published npm package — ship the docs directory (package.json "files" field) so the existing docs/config.md content is actually reachable from an install.
5. docs/config.md — already documents the syntax well (headers/env schema rows and the placeholder section); keep it as the source of truth but make it reachable per point 4.
6. JSON schema property descriptions for env and headers in the config schema, so editor/IDE validation surfaces the format.
7. Runtime error handling — when a header/env value contains the unsupported ${env:...} pattern, fail fast with a clear error naming the variable instead of silently sending the literal string (which manifests as opaque 401/403 auth failures); either translate ${env:VAR} to the mcporter syntax or reject it explicitly.
8. docs/import.md — imported Cursor/Claude/Codex/OpenCode configs very commonly use ${env:VAR} in mcpServers headers, so the import reference is the most likely place a user will inherit this syntax from and should warn that mcporter does not expand it.

Environment

• mcporter 0.13.7 (latest as of filing)
• Reproduced with an HTTP (SSE) remote MCP server and a Bearer auth header
• Also verified the code path in dist/env.js resolveEnvPlaceholders and dist/runtime-header-utils.js materializeHeaders

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 24, 2026, 4:33 AM ET / 08:33 UTC.

Summary
Keep open: current main still lets ${env:VAR} pass through literally in header and stdio environment resolution, and the linked open PR already owns the focused repair.

Reproducibility: yes. —current source provides a high-confidence path: resolve Bearer ${env:VAR} with VAR set and the unsupported token does not match the interpolation expression, so it remains literal.

Next step
The linked open PR already owns the bounded repair, so no duplicate fix PR should be queued.

Review details

Best possible solution:

Review and land the existing focused PR, preserving its early rejection, concise CLI/package guidance, and HTTP-plus-stdio regression coverage.

Do we have a high-confidence way to reproduce the issue?

Yes—current source provides a high-confidence path: resolve Bearer ${env:VAR} with VAR set and the unsupported token does not match the interpolation expression, so it remains literal.

Is this the best way to solve the issue?

Yes—the linked PR's fail-fast rejection with corrective syntax is narrower and safer than silently translating an unsupported convention.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against ae3d9000c320.

Label changes

Label justifications:

• P2: Unsupported placeholder syntax can cause opaque authentication failures but has a bounded configuration and transport scope.
• impact:auth-provider: A literal Authorization header can fail authentication despite the intended environment value being set.
• impact:ux-friction: CLI and package-facing guidance does not clearly prevent this syntax mistake.

Evidence reviewed

What I checked:

• Current resolver behavior: The interpolation expression requires an identifier directly after ${; ${env:VAR} does not match and is retained unchanged. (src/env.ts:5, ae3d9000c320)
• HTTP and stdio paths: Headers are resolved through the shared resolver before HTTP transport creation, while stdio environment overrides use resolveEnvValue, which also delegates dollar-prefixed values to that resolver. (src/runtime-header-utils.ts:15, ae3d9000c320)
• Discoverability remains incomplete: Current schema/config docs name supported forms, but config-add help still describes --env and --header only as repeatable attachments; README omits syntax and the published package excludes docs/. (src/cli/config/help.ts:51, ae3d9000c320)
• Release check: The same resolver is present in the v0.13.6 release commit, confirming the reported behavior is shipped rather than a main-only regression. (src/env.ts:5, e53ef107e4c9)
• Existing implementation candidate: The supplied GitHub context identifies the open linked PR as formally closing this issue; it proposes early rejection, corrective guidance, documentation, and regression coverage, so another repair PR would duplicate work. (37326cef43fe)

Likely related people:

• Peter Steinberger: Current blame attributes the resolver to the release commit, and feature history shows repeated ownership of configuration, runtime, and header-related work. (role: long-running core contributor and current-source attribution; confidence: medium; commits: e53ef107e4c9, 3f4f8dc317e4; files: src/env.ts, src/runtime-header-utils.ts, src/cli/config/help.ts)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

Confirmed on current main: unsupported ${env:VAR} syntax escapes the interpolation matcher and is sent verbatim (reproduced with the built CLI — 4 HTTP requests carried the literal placeholder). Until #324 lands, use ${VAR} or ${VAR:-fallback} within values, or whole-value $env:VAR. #324 adds explicit rejection of unsupported syntax plus package-visible guidance; its CI has been approved and it's queued to land. Keeping this open until the fix merges.