Repository navigation
fix(mcp): name an mcp env placeholder that will not resolve - #31562
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Each item answers the reproduced Dock-launch failure, and nothing in the repo already reports an unset stdio-env reference at session level. Notes
What this change shipsInventory (8 items) — 7 justifiedIntent: someone who opens the app from the Dock can see which MCP server's
[FIRST-PRINCIPLES-REVIEWED] 4878192 Description read[DESCRIPTION-READ] 69744b1b979dd7ea6ec48ae65ec6be0c63f3e8ebd9cab4701256e7291dbed4eb That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the change only adds a diagnostic, built as the twin of the existing header-secret guard, and no session behaviour changes. Notes
[DESIGN-REVIEWED] 4878192 Description read[DESCRIPTION-READ] a355b9d21481ff0e4a275a2e6691396d79169751e0d48c08b0d45d6c78209134 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
b9bcb9c to
3cc9f40
Compare
|
[operator: bolichen97]
|
|
[operator: bolichen97]
|
|
[operator: bolichen97] The shard-2 reds on this head ( That red is main's, not this change's: this PR touches nothing under |
3cc9f40 to
eab8f67
Compare
|
[operator: bolichen97] Rebased: main moved in same-directory files under |
|
[operator: bolichen97] The shard-7 reds on this head ( That red is main's, not this change's: this PR touches nothing under The five AI review lanes on this head (Design, First Principles, GPT 6.1, Opus 5.5, UX) failed before producing a verdict because the shared installation token hit GitHub's API rate limit; each failed job was re-run once after the hourly reset. |
|
[operator: bolichen97] The It is not this change's: the test builds every provider as an No rerun: |
An MCP server whose env holds ${NAME} or ${env:NAME} for a variable
the gateway does not have starts with the literal text as that value.
The usual cause is an app opened from Finder or the Dock: it inherits
launchd's environment and never reads the shell profile that exports
the token, so the server answers every call with an authorization
error and nothing in the session says why.
At session start, beside the remote-header secret:// guard it mirrors,
mcp_ref_guard.warn_unset_env_placeholders names each such stdio server
and variable in one log line and on the session's MCP problem summary.
Names only, never a value: a reference that is not a plain identifier,
such as ${NAME:-default}, is skipped. The server still starts as
before, so the names-only summary a spawned run's prompt gets leaves
the entry out. Each server is judged against the environment that
expands it: the kiro-cli child's scrubbed environment for a spec
server kiro-cli starts itself, the routed path's placeholder view for
every other. Both composition sites, AcpClient and AcpRuntime, call
it.
The macOS troubleshooting guide gains a section on the symptom, how to
spot it, and the two routes that supply the value whatever the launch
path: the vault with a routed server, or the data home's .env file.
The owning spec in docs/architecture/mcp.md records the check, and the
two descriptions of ACP_BACKENDS_SPEC_SERVERS_OFF_WIRE name it as a
reader.
Closes #4970
eab8f67 to
4878192
Compare
|
self-added: no
|
|
[operator: bolichen97] Rebased: main moved in |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Tier 1 auto-approve: fix (11 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: logs a names-only warning and records a session MCP summary entry when a stdio server env references an unset variable; the server still starts as before. Spec files changed as a ride-along (a minority of the diff on both file count and changed lines), not reviewed as a design decision: docs/architecture/mcp.md.
An MCP server whose env holds ${NAME} or ${env:NAME} for a variable
the gateway does not have starts with the literal text as that value.
The usual cause is an app opened from Finder or the Dock: it inherits
launchd's environment and never reads the shell profile that exports
the token, so the server answers every call with an authorization
error and nothing in the session says why.
At session start, beside the remote-header secret:// guard it mirrors,
mcp_ref_guard.warn_unset_env_placeholders names each such stdio server
and variable in one log line and on the session's MCP problem summary.
Names only, never a value: a reference that is not a plain identifier,
such as ${NAME:-default}, is skipped. The server still starts as
before, so the names-only summary a spawned run's prompt gets leaves
the entry out. Each server is judged against the environment that
expands it: the kiro-cli child's scrubbed environment for a spec
server kiro-cli starts itself, the routed path's placeholder view for
every other. Both composition sites, AcpClient and AcpRuntime, call
it.
The macOS troubleshooting guide gains a section on the symptom, how to
spot it, and the two routes that supply the value whatever the launch
path: the vault with a routed server, or the data home's .env file.
The owning spec in docs/architecture/mcp.md records the check, and the
two descriptions of ACP_BACKENDS_SPEC_SERVERS_OFF_WIRE name it as a
reader.
Closes #4970
(cherry picked from commit 2c8e9aa)
…0898) A cron or webhook run on the default KAS backend sent its first prompt before a slow MCP server was up, so the run silently had no tools. The wait only declared servers on kiro-cli. KAS reports each wire server in _kiro/mcp/status, so declare the spec servers the wire array carries. Fixes #30325 (cherry picked from commit 120d913) Original author: Ray Xu (#30898). Applied on top of #31562 (batch 28), so runtime_session_setup.py matches main for this change.
…0898) A cron or webhook run on the default KAS backend sent its first prompt before a slow MCP server was up, so the run silently had no tools. The wait only declared servers on kiro-cli. KAS reports each wire server in _kiro/mcp/status, so declare the spec servers the wire array carries. Fixes #30325 (cherry picked from commit 120d913) Original author: Ray Xu (#30898). Applied on top of #31562 (batch 28), so runtime_session_setup.py matches main for this change.
Problem / Motivation
Goal: When an MCP server's
envnames a variable the gateway does not have, the session-start log line and the session's MCP problem summary name the server and the variable, and the macOS guide shows how to give an app opened from Finder or the Dock that value.A server declared with
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}" }works when Kiro Crew starts from Terminal. Opened from Finder or the Dock, the app inherits launchd's environment and never reads~/.zprofile, so the server starts with the literal text${GITHUB_PAT}as its token. Every call then fails with an authorization error. The chat, the dashboard row and the session's MCP report say nothing about why; the only trace is adeclared env placeholder ... is unsetline thatgateway.loggets while the spec is built.Why it matters
Anyone who keeps an MCP token in their shell profile and opens the desktop app from the Dock gets a server that looks configured and healthy but never works. Nothing at session level points at the missing variable, and a run nobody watches (a task step, a webhook run, a subagent) reports nothing about it.
Not a goal
mcp.jsonwhatever the launch path.${env:NAME}in a remote server's headers, which a different reader expands.mcp.jsoninto a hand-written agent spec that leavesincludeMcpJsonon. Crew-written specs pin it off, and the check reads only the session's spec and array.agent.env: the check reads no config, so a name that onlyagent.envgives kiro-cli is still named.What changed (motivation → approach → change)
Cause. A
${NAME}that the environment expanding the server does not hold reaches the server as literal text, and nothing at session level says so.Approach. The remote-header
secret://guard inacp/mcp_ref_guard.pyalready handles the same "it starts but cannot authenticate, and nothing says why" case at session start: one log line, one entry on the session's MCP report, no change to the session. This adds its stdio-env twin instead of a new mechanism.Change.
warn_unset_env_placeholdersruns beside the header guard at both session-start sites,AcpClientandAcpRuntime. It finds${NAME}and${env:NAME}in each stdio server'senvwith the rewriter's own_ENV_VAR_PLACEHOLDER, and judges each name against the environment that will expand it. For a spec server kiro-cli starts itself, that is the names the shared launch tail (acp/launch.py) put in the kiro-cli child's environment, recorded per spawn as_child_env_nameson both drivers, so a nameagent.envsupplies counts as set and the scrub is already applied. Every other server is judged against_placeholder_source_env(), which the routed and session-array paths expand from. Only servers the session starts are judged: kiro-cli's enabled spec servers, a spec server the array as sent carries, and the array's own elements. A server pruned as unstartable is skipped, and so is a KAS spec server off the wire, whose env KAS's projection withholds or hands to Crew's launcher, which logs an unset name itself. The check reads no config and no disk. A miss is logged once per session and recorded byMcpSessionReport.record_env_placeholder_refs, soproblem_summary()names it for task steps and webhook runs. Only names are reported: a reference that is not a plain identifier, such as${NAME:-default}, is skipped because its text can carry a value. The names-only summary that a spawned run's prompt gets leaves the entry out, because that prompt says its servers are not mounted and this server did start. The macOS guide gains "An MCP server's${VAR}works from Terminal but not from the app", recommending only the two routes measured on a Dock-style launch: the vault with a routed server, and a data-home.envline with its not-agent-isolated caveat.docs/architecture/mcp.mdrecords the check.Backwards compatibility
Compatible: the check only reads the spec, the wire array and the environment, then adds a log line and a report entry; every session starts and runs as before.
Removes nothing: no field, key, route or behaviour is taken away,
record_header_secret_refskeeps its contract, and the names-only summary reads as on main.Tests
test/test_mcp_unset_env_placeholders.py::test_an_unset_placeholder_is_named_and_no_value_islocks in:{"TOKEN": "${KC4970_UNSET}", "HOME_DIR": "${HOME}", "MODE": "${KC4970_UNSET:-kc4970default}"}yields exactly one entry, naming the server andKC4970_UNSET, and the log line carries neither the home path nor the default text;AcpClientand theAcpRuntimesession-start guards both put that entry inproblem_summary(), and the names-only reading leaves it out;AcpClientpruned as unstartable is not named;agent.envsupplies, is not named on kiro-cli; on KAS a spec server is judged only when the array carries it, and then against the routed view;test/test_acp_launch_goldens.py::test_the_child_environment_is_built_in_one_fixed_orderalso asserts that the launch tail records exactly the names the child was spawned with.Each of these breakages, applied alone, fails a test by assertion: reporting a non-identifier reference, judging every server against the routed view, judging kiro-cli's own servers against the gateway's environment instead of the child's, keeping the entry in the names-only summary, dropping the
AcpClientrecorder call, dropping theAcpRuntimerecorder call, not recording the child's names in the launch tail, judging a server the attempt pruned, judging a KAS spec server the array does not carry.Determinism: both tests pass 20 of 20 at
-n0; their two files with the two sibling files (test_mcp_remote_header_secret_refs.py,test_mcp_session_report.py), 136 node ids, pass in two shuffled orders (seed=4970 and seed=27017). The flake-pattern ratchet passes. The 39 test files that reference the changed modules, the backend cards or the MCP spec (2776 tests) pass at-n 2.Proof: PROVEN test/test_acp_launch_goldens.py::test_the_child_environment_is_built_in_one_fixed_order (head e39d24656174)
Manual verification
macOS 26.7.2 on Apple silicon. D1-D5 were measured with the gateway from main at d8d4b05. The "with this change" lines below come from an earlier revision of this change whose warning differed only in its advice wording. The head's later changes (which environment each server is judged against, which servers are judged, skipping a non-identifier reference) give the same answer in these runs:
GITHUB_PATis unset in both views for D2 and D3 and set in both for D1. The head is rebased on current main; the proof line above names an earlier head that carries the same patch. A dummy value stood in for the token, and a probe MCP server reported only a sha256 prefix of what it received (6f3d339fa760is the dummy).How each launch was made:
GITHUB_PATruns the launcher directly.open -n) of a small app bundle built for the test, started with an emptied caller environment (env -i open). Measured first:openrun from a shell forwards that shell's whole environment to the app,GITHUB_PATincluded. Underenv -ithe app got launchd's environment (HOME,PATH,SHELL,TMPDIR,USER, theXPC_*and__CF*names and similar) plus the few names the bundle's/bin/shadds, and noGITHUB_PAT.gateway-env.js,mac-env.jsandsystem-proxy-env.js, composed asgateway-supervisor.jsdoes, then starts the gateway. The packaged app was not built.${NAME}from its own environment as kiro-cli does and completes an MCP handshake with each stdio server, a session-injected entry outranking the spec entry. No model turn ran.${GITHUB_PAT}, unrouted${GITHUB_PAT}, unrouted${GITHUB_PAT}GITHUB_PAT=<dummy>in the data-home.envsecret://GITHUB_PATsaved through the Secrets API, routedD5 needed the launch approved again, through the same API, after the env value changed. With this change, D2 and D3 each add one line per session,
stdio MCP server env references a variable that is not set: backend='' agent='kirocrew' servers=kc4970-github ('GITHUB_PAT'), and D1 adds nothing.Screenshots / video
N/A -- no frontend change.
Related Issues
Closes #4970
Sibling sweep
Swept: git grep -nE "_ENV_VAR_PLACEHOLDER|_expand_env_map(|expand_entry_env(|keep_env_references(|_expand_env_placeholders(" -- src/
Siblings: none -- every expander it finds (the routed sidecar, the session array, the KAS launch snapshot, the home-name pass) leaves a miss literal by design and tells the session nothing; the one session-level notice for all of them is the guard both composition sites call, and remote headers are listed under Not a goal
Pattern harvest
Rule candidate: review-prompt
Pattern: an environment reference that a launch path leaves unresolved reaches a server as literal text with nothing session-visible naming it; the remote-header
secret://guard is the precedent this appliesChecklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license (see CONTRIBUTING.md).