anthropics / anthropics/claude-code
envHelper: settings-configurable command to supply env vars for config expansion (MCP configs, desktop app)
- Vorherrschende Sprache
- Python
- Sterne
- 145k
- Forks
- 23.1k
- PR-Merge-Kennzahlen
- PR-Kennzahlen ausstehend
Beschreibung
## Problem
`${VAR}` expansion in MCP configs reads from Claude Code's own process environment. In the desktop app there is no shell in the launch path, so there is no good way to supply those variables, which pushes users toward pasting plaintext tokens into `~/.claude.json`. The CLI has the same gap in a milder form: to feed env vars into MCP config expansion you have to wrap the whole session in an env-injecting launcher (e.g. `varlock run -- claude`, `op run -- claude`, `doppler run -- claude`), which is invocation-dependent and does not survive launching from an IDE or the desktop app.
`headersHelper` covers part of this, but only for HTTP/WS servers, only for headers, and per-server. It is also excluded from the MCP discovery cache (`discovery-cache: headers-helper — purging this server's cache-key family, serving miss`), so it re-runs at every session start. For helpers backed by a secrets manager that gates access on user presence (Touch ID / Windows Hello), that means an auth prompt on every session, including sessions that never use the server. Prompt fatigue then drives users back to plaintext tokens, which is the worst outcome.
## Proposal
An `envHelper` setting (user and project scope), following the existing `apiKeyHelper` / `awsCredentialExport` pattern: a command that prints a JSON object of env var names to values.
```json
// ~/.claude/settings.json or .claude/settings.json
{
"envHelper": "varlock load --format json"
}
```
Suggested semantics:
- **Lazy**: run the helper on the first `${VAR}` expansion miss, not at startup. Combined with the MCP discovery cache, a session that never connects to a server needing these vars never runs the helper.
- **Merged into the expansion environment**: applies wherever `${VAR}` expansion already works (`command`, `args`, `env`, `url`, `headers`), including stdio server `env` blocks, so one helper serves N servers. Real environment variables take precedence; the helper fills misses.
- **Cached for the app process lifetime**, with an optional TTL and re-run on MCP 401/403 retry as the refresh path (mirroring how `awsCredentialExport` output is cached until expiry). This gives secret-manager-backed setups one consent prompt per app launch, only when actually needed, and Claude Code never persists the values.
- **Scope layering**: user-level helper for personal secrets, project-level for project env, so `.mcp.json` files with `${VAR}` references become invocation-independent across the CLI, desktop app, and IDE extensions.
## Why not the existing mechanisms
- Plaintext `headers`/`env` in config: the thing this is trying to avoid.
- `headersHelper`: HTTP-only, per-server, runs every session start due to the discovery-cache exclusion; no equivalent exists for stdio server `env`.
- OAuth: right answer where servers implement it, but many internal/API-token servers never will.
- Wrapping the launch (`varlock run -- claude`): works in a terminal, impossible from the desktop app, and couples the session to how it was launched.
For comparison, VS Code solves this custodially (MCP `inputs` with `password: true` prompt once and store in VS Code Secret Storage). An `envHelper` is the non-custodial version: the harness never stores a secret, it just knows what command to ask, and any secrets manager plugs in.
Beitragsleitfaden
Für dieses Repository ist kein Beitragsleitfaden indexiert
Rechercherichtung
Start by tracing the existing apiKeyHelper and awsCredentialExport handling, headersHelper behavior, and ${VAR} expansion across ~/.claude/settings.json, .claude/settings.json, and .mcp.json. Check how MCP discovery caching and scope layering work; done means a lazy, merged, process-cached helper works across CLI, desktop app, and IDE extensions without persisting values.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Bereich
- cli, desktop, tooling
- Issue-Typ
- Feature
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Aktivitätsstatus
- Aktiv
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 35/100