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 23, 2026, 12:09 PM ET / 16:09 UTC.

Summary
Keep open: current main still silently retains ${env:VAR} in interpolated header values, and the linked open repair PR already owns the focused fix.

Reproducibility: yes. —source provides a high-confidence path: pass Bearer ${env:VAR} to header materialization with VAR set; the current regex does not match it and the header path retains the literal value.

Root-cause cluster
Relationship: canonical
Canonical: #323
Summary: This is the canonical report; the linked open PR is the candidate repair for the same confirmed placeholder-resolution and discoverability problem.

Members:

• fixed_by_candidate: fix(config): reject unsupported env placeholders #324 - It directly rejects the unsupported syntax at HTTP and stdio boundaries and adds the requested guidance, but has not merged.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Next step
The open linked PR already owns the focused implementation; do not start a duplicate repair.

Review details

Best possible solution:

Land a rebased focused repair that rejects ${env:VAR} before either transport boundary and exposes accepted syntax in CLI help and npm-reachable documentation.

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

Yes—source provides a high-confidence path: pass Bearer ${env:VAR} to header materialization with VAR set; the current regex does not match it and the header path retains the literal value.

Is this the best way to solve the issue?

Yes—the linked PR's fail-fast rejection with corrective syntax is the narrowest compatible fix; silently translating another client's convention would broaden the established contract.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• fix(config): reject unsupported env placeholders #324 is currently reported as dirty against main, so it needs a rebase or refreshed merge review before it can resolve this issue.

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

Label changes

Label justifications:

• P2: Unsupported placeholder syntax can send a literal bearer value and cause a bounded authentication failure.
• impact:auth-provider: The literal value reaches HTTP authorization headers and manifests as authentication failure.
• impact:ux-friction: The supported syntax is absent from config-add help and the published README, causing opaque troubleshooting.

Evidence reviewed

What I checked:

• Current grammar misses the reported syntax: The interpolation pattern accepts ${NAME} and ${NAME:-fallback} only; ${env:NAME} does not match and is not diagnosed or replaced. (src/env.ts:5, ae3d9000c320)
• Unmatched headers are forwarded: Header materialization stores the resolver result, allowing an unmatched ${env:VAR} value to reach the HTTP transport. (src/runtime-header-utils.ts:14, ae3d9000c320)
• Installed-package guidance is incomplete: Config-add help gives only repeatable key/value descriptions; README mentions placeholders without syntax; package publishing omits docs/config.md. (src/cli/config/help.ts:51, ae3d9000c320)
• Existing contract and history: The schema and detailed config guide define the supported forms, while history identifies the original environment-placeholder work as Peter Steinberger's ea9108627350e5f393ec80678ae1f6e94694a742. (src/config-schema.ts:117, ea9108627350)
• Open candidate fix: The linked PR explicitly addresses both early rejection and documentation, includes real CLI proof for HTTP and stdio, but remains open. (37326cef43fe)

Likely related people:

• Peter Steinberger: Repository history identifies him as author of the original config environment-placeholder fix and the available resolver history. (role: introduced environment-placeholder behavior; confidence: medium; commits: ea9108627350, e53ef107e4c9; files: src/env.ts, src/runtime-header-utils.ts, src/config-schema.ts)
• Krasimir Kralev: Most recently updated the relevant config documentation path. (role: recent configuration-docs contributor; confidence: medium; commits: c89ad9c4ecd4; files: docs/config.md)

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.