Skip to content

fix(mcp): name an mcp env placeholder that will not resolve - #31562

Merged
bolichen97 merged 1 commit into
mainfrom
fix/4970-mcp-env-placeholder-notice
Nov 7, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/4970-mcp-env-placeholder-notice

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When an MCP server's env names 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 a declared env placeholder ... is unset line that gateway.log gets 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

  • Importing the login-shell environment into the app or the gateway on a GUI launch. The app deliberately never runs shell startup files, and the vault already keeps the token out of mcp.json whatever the launch path.
  • Changing what starts: the server still starts exactly as today, with the literal value. Nothing is pruned, refused or marked failed, and a spawned run's prompt is unchanged.
  • A dashboard or chat UI change, or a new payload key.
  • A ${env:NAME} in a remote server's headers, which a different reader expands.
  • Servers kiro-cli merges from the global mcp.json into a hand-written agent spec that leaves includeMcpJson on. Crew-written specs pin it off, and the check reads only the session's spec and array.
  • Reading agent.env: the check reads no config, so a name that only agent.env gives kiro-cli is still named.
  • The existing spec-build log line that calls a set variable "credential-filtered"; it is unchanged here.

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 in acp/mcp_ref_guard.py already 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_placeholders runs beside the header guard at both session-start sites, AcpClient and AcpRuntime. It finds ${NAME} and ${env:NAME} in each stdio server's env with 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_names on both drivers, so a name agent.env supplies 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 by McpSessionReport.record_env_placeholder_refs, so problem_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 .env line with its not-agent-isolated caveat. docs/architecture/mcp.md records 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_refs keeps 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_is locks in:

  • a server whose env is {"TOKEN": "${KC4970_UNSET}", "HOME_DIR": "${HOME}", "MODE": "${KC4970_UNSET:-kc4970default}"} yields exactly one entry, naming the server and KC4970_UNSET, and the log line carries neither the home path nor the default text;
  • the AcpClient and the AcpRuntime session-start guards both put that entry in problem_summary(), and the names-only reading leaves it out;
  • a server the AcpClient pruned as unstartable is not named;
  • a name only the kiro-cli child's environment holds, as one agent.env supplies, 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;
  • once the variable is set, nothing is reported.

test/test_acp_launch_goldens.py::test_the_child_environment_is_built_in_one_fixed_order also 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 AcpClient recorder call, dropping the AcpRuntime recorder 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_PAT is 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 (6f3d339fa760 is the dummy).

How each launch was made:

  • Terminal: a login zsh whose profile exports the dummy GITHUB_PAT runs the launcher directly.
  • Finder/Dock stand-in: a LaunchServices launch (open -n) of a small app bundle built for the test, started with an emptied caller environment (env -i open). Measured first: open run from a shell forwards that shell's whole environment to the app, GITHUB_PAT included. Under env -i the app got launchd's environment (HOME, PATH, SHELL, TMPDIR, USER, the XPC_* and __CF* names and similar) plus the few names the bundle's /bin/sh adds, and no GITHUB_PAT.
  • The launcher builds the gateway environment with the desktop shell's own gateway-env.js, mac-env.js and system-proxy-env.js, composed as gateway-supervisor.js does, then starts the gateway. The packaged app was not built.
  • kiro-cli: the packaged fake ACP backend behind a wrapper that expands ${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.
Step Launch and route Server received gateway.log on main Session and dashboard on main
D1 Terminal, ${GITHUB_PAT}, unrouted the value (prefix matches) three "names a credential-filtered variable" lines, although the value resolved row ok
D2 Dock stand-in, ${GITHUB_PAT}, unrouted literal ${GITHUB_PAT} "declared env placeholder 'GITHUB_PAT' for MCP server 'kc4970-github' is unset", at spec build chat silent, row ok with no error
D3 Dock stand-in, routed, launch approved through the MCP page's launch-approval API literal, from the broker's backend the same unset line chat silent, row ok
D4 Dock stand-in, GITHUB_PAT=<dummy> in the data-home .env the value, unrouted and routed "Unknown key GITHUB_PAT in .env ... NOT agent-isolated" row ok
D5 Dock stand-in, secret://GITHUB_PAT saved through the Secrets API, routed the value until the launch was approved again, "resolves to a launch the operator has not approved ... Re-approve it from the MCP page"; unset-placeholder lines like D2's also appear row routed

D5 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 applies

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license (see CONTRIBUTING.md).

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 16:42
@bolichen97 bolichen97 added the ci:macos Run the on-demand macOS suite against this PR head label Nov 6, 2026
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 16:42
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 16:43
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 487819253f7308ed7709043c2080f3a1cca90c8d touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 487819253f7308ed7709043c2080f3a1cca90c8d — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • Item 1 — duplicate: mcp_gateway/rewriter_env.py:227 already logs "declared env placeholder %r for MCP server %r is unset" when the spec is built, so the same miss is now logged twice. Subtraction: once the session-level line ships, delete the spec-build warning (or drop it to debug), so only one line names the cause.

What this change ships

Inventory (8 items) — 7 justified

Intent: someone who opens the app from the Dock can see which MCP server's ${VAR} never resolved. FIX: a diagnostic that leaves session behaviour unchanged.

  1. At session start, gateway.log gets one line naming each stdio server and its unset variable. Tagged duplicate (see Notes): rewriter_env.py's spec-build warning already covers the same miss.
  2. The session's MCP problem summary names that server and variable, so a task step or webhook run reports it — justified
  3. The names-only summary a spawned run's prompt gets leaves the entry out — justified
  4. A ${NAME:-default} reference is skipped, so no default text is ever logged — justified
  5. Each kiro-cli spawn records the names in the child's environment (_child_env_names) — justified
  6. New macOS guide section: "${VAR} works from Terminal but not from the app" — justified
  7. docs/architecture/mcp.md describes the check — justified
  8. The entry-sanitizing loop moves into _guard_entries, which the header and env recorders both call — justified

[FIRST-PRINCIPLES-REVIEWED] 4878192

Description read

[DESCRIPTION-READ] 69744b1b979dd7ea6ec48ae65ec6be0c63f3e8ebd9cab4701256e7291dbed4eb

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 487819253f7308ed7709043c2080f3a1cca90c8d — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • The kiro-cli half rests on an unstated assumption: that kiro-cli expands ${NAME} in a spec server's env from its own child environment. If it doesn't, the message points users at a cause that isn't theirs. It is easy to revert, but a test or doc reference stating kiro-cli's expansion rule would anchor it.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 487819253f7308ed7709043c2080f3a1cca90c8d — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 4878192

Verdict parsed from the review's SHA-scoped output markers for commit 487819253f7308ed7709043c2080f3a1cca90c8d.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 487819253f7308ed7709043c2080f3a1cca90c8d false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 487819253f7308ed7709043c2080f3a1cca90c8d and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 4878192

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 487819253f7308ed7709043c2080f3a1cca90c8d false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/4970-mcp-env-placeholder-notice branch from b9bcb9c to 3cc9f40 Compare November 6, 2026 18:03
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

  • span=2f5802adc3cd kiro-cli spec servers were judged without agent.env

fixed in 3cc9f40: the shared launch tail now records the names it put in the child's environment (host._child_env_names, after agent.env, the driver's own variables and the scrub), and the guard judges a spec server kiro-cli starts itself against those names.
A name agent.env supplies now counts as set, so no false "starts with the literal text" line or problem-summary entry for a server that resolves it.
The suggested agent_env_overlay() call was not used: both guard sites are documented synchronous and in-memory (H13), and that call reads config from disk on the event loop. The recorded names cost no read.
Pinned by test_mcp_unset_env_placeholders.py (an agent.env-only name is not named on kiro-cli, is named on KAS) and test_acp_launch_goldens.py::test_the_child_environment_is_built_in_one_fixed_order (the recorded names equal the spawned env's).

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

  • span=5f1772bc7bac diagnostic ignored the launch's SSH-agent forwarding verdict

fixed in 3cc9f40: the guard no longer re-derives the kiro-cli view with scrub_agent_subprocess_env() and its default verdict. It reads the names the launch tail recorded after scrub_agent_subprocess_env(env, forward_ssh_auth_sock=...) ran with that spawn's resolved verdict, so a forwarded SSH_AUTH_SOCK counts as set and a withheld one does not.
No new plumbing of the verdict: the one recorded name set covers it, beside the same change that answers the Opus finding on this line.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 6, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] The shard-2 reds on this head (Backend Tests (3.12, 2), Backend Tests (Windows) (2), macOS Tests / Backend Tests (macOS) (2), and the Coverage Gate that fails closed behind them) are one test: test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget (the security package is at 34,753 lines against a budget of 34,733).

That red is main's, not this change's: this PR touches nothing under src/kiro_crew/security/, the package and that test are byte-identical to current main (f9e8bdfa), and the node id fails locally on them. It is tracked in #31648 and the budget fix is #31625. This PR waits for that fix to merge, then rebases onto it and re-runs CI; no rerun until then, since the test is deterministic.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/4970-mcp-env-placeholder-notice branch from 3cc9f40 to eab8f67 Compare November 6, 2026 20:36
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Rebased: main moved in same-directory files under docs/system-specs/modules/, src/kiro_crew/acp/, src/kiro_crew/agent_sdk/ and test/ (none of the files this PR changes) since this head's CI ran (8095bc3 -> 39717a0); CI re-running. The new base carries #31625, which raises the security package line budget behind the shard-2 reds (test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget) on the previous head. The diff is unchanged (same patch id); new head eab8f67.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 6, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] The shard-7 reds on this head (Backend Tests (3.12, 7), Backend Tests (Windows) (7), and the Coverage Gate that fails closed behind them) are one test: test/test_pull_request_target_allowlist.py::test_only_the_allowed_workflows_use_pull_request_target (sensitive-change-review.yml uses pull_request_target but is not in that test's allowlist).

That red is main's, not this change's: this PR touches nothing under .github/ and does not touch that test, both are byte-identical to the base this head sits on, and the node id fails locally on them. It is tracked in #31771 and the fix is #31803. This PR waits for that fix to merge, then rebases onto it and re-runs CI; no rerun until then, since the test is deterministic.

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.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] The macOS Tests / Backend Tests (macOS) (3) red on this head is one test: test/test_subagent_injection_channel_timeout_resend.py::test_a_timeout_after_a_reload_reads_the_session_that_received_the_completion, which hit its 30s hang ceiling (TimeoutError).

It is not this change's: the test builds every provider as an AsyncMock and patches stream_and_collect, so no code this PR changes runs in it. On this head it passed in the Linux and Windows backend shards, and the node id passed 8 of 8 runs locally on macOS at this head. Recorded in the flake ledger as #31835.

No rerun: #31803 (the shard-7 fix) is now on main, so this PR rebases onto it once the lanes still running on this head finish, and the new head re-runs the macOS suite.

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
@bolichen97
bolichen97 force-pushed the fix/4970-mcp-env-placeholder-notice branch from eab8f67 to 4878192 Compare November 7, 2026 00:07
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: which servers the env-placeholder guard judges (_stdio_envs)
[operator: bolichen97]

  • span=5f1772bc7bac omitted servers were judged by the unset-placeholder diagnosis

fixed in 4878192: the AcpClient site hands the env guard the array as sent, not the copy carrying the pruned-name entries, so a server pruned as unstartable no longer counts as carried and is not named. Its failed row still names the real cause.
KAS spec servers off the wire are no longer judged from the raw spec: only the servers KAS's projection declares launch, and that projection withholds their env or hands it to Crew's launcher, whose _expand_env_map logs the unset name and server for exactly the servers it starts. A KAS spec server the array carries is still judged, against the routed view.
Not plumbing the projection into the guard: its env no longer holds the ${NAME} text, so it could only filter names the launcher's own line already covers.
Regression: test_an_unset_placeholder_is_named_and_no_value_is asserts a pruned goose server is not named and a KAS spec server the array does not carry is not judged; each assertion fails with its half of the fix reverted.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Rebased: main moved in docs/architecture/mcp.md (a different section) and in same-directory files under docs/system-specs/modules/ (none of the files this PR changes) since this head's CI ran (39717a0 -> 594344f); CI re-running. The new base carries #31803, the fix for the shard-7 red (test/test_pull_request_target_allowlist.py::test_only_the_allowed_workflows_use_pull_request_target) on the previous head. The same push carries the fix for the GPT 6.1 finding, answered in its own comment. New head 4878192.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 7, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@bolichen97
bolichen97 merged commit 2c8e9aa into main Nov 7, 2026
101 of 105 checks passed
@bolichen97
bolichen97 deleted the fix/4970-mcp-env-placeholder-notice branch November 7, 2026 02:06
buluoray pushed a commit that referenced this pull request Nov 7, 2026
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)
buluoray added a commit that referenced this pull request Nov 7, 2026
…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.
buluoray added a commit that referenced this pull request Nov 7, 2026
…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:macos Run the on-demand macOS suite against this PR head readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MCP servers in ~/.kiro/settings/mcp.json: ${VAR} env substitutions are never expanded

2 participants