Skip to content

fix(mcp-gateway): show a vault-secret server as routable - #24918

Merged
bolichen97 merged 1 commit into
mainfrom
fix/24555-vault-env-routable-row
Oct 29, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/24555-vault-env-routable-row

Conversation

@JLargent42

@JLargent42 JLargent42 commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: In MCP Management, a server whose env names a vault secret (secret://) reads as routable, and its STUB toggle offers the launch for approval, instead of reading direct (env).

With sharing on and mcp_gateway.forward_declared_env off, every env-declaring server row reported pooling_blocked_by_env, so the page showed it as direct (env) ("Not stubbed, but your opt-in stays saved"). The rewriter does not treat that case as direct: _needs_private_backend gives a server whose env names a vault secret a connection-private backend the gateway starts. The row and the stub eligibility check did not apply that exception, so the documented secret:// route (docs/guides/secrets-env.md) looked unavailable.

Why it matters

A user on the default KAS backend whose credentialed stdio server is left unwrapped gets no env on the wire. The secret:// route through the gateway is the supported way out, and the page told them it would not work.

Not a goal

What changed (motivation → approach → change)

Symptom: a secret:// server with routing on read direct (env). Cause: the row checked only "would a shared backend withhold env", not the rewriter's vault-secret exception. Fix: the row asks the rewriter's two predicates (_withheld_env_count, _needs_private_backend) for each declaration and reports the new private_backend flag.

Part Change
Rows (mcp_gateway_routes.py) _collect_server_rows records, per declaration, the env key names and which keys hold a secret:// value (names only, never values). The new _env_pooling_outcome returns (blocked, private). private needs every declaration to be private, so an env-less declaration elsewhere keeps the row shared. A name declared both ways stays blocked, because the rewriter leaves the plain declaration unwrapped.
Eligibility (mcp_gateway_stubs.py) _stub_eligibility skips for pooling_blocked_by_env only when a declaration is actually left unwrapped. A server whose every declaration gets a private backend has no co-tenants, so with sharing on it is judged on recommend_stub, not recommend_share.
Page (mcpManagementModel.ts, website/src/api/client/mcp.ts) The row type gains private_backend. A stubbed row with it takes the stub state (label key state_stub), not shared: its backend is its own. Its Details reason is the new why_private_backend (added to website/src/i18n/locales/en.manual.json, every translated catalog and the regenerated en-XA.json), not why_stub_off, which says sharing still has to be turned on.

Backwards compatibility

Compatible: private_backend is a new optional field, and an older gateway that does not send it renders as before. pooling_blocked_by_env only changes from true to false for vault-secret declarations.

Removes nothing: the change adds a field and narrows one false positive. No key, row or route goes away.

Tests

  • TestGatewayServers::test_a_vault_reference_gets_a_private_backend_not_direct_env: a vault-secret row is not blocked and is private_backend. A plain-env row stays blocked. A name declared both ways stays blocked. A name declared once with a vault secret and once with no env is shared, not private. The secret value never appears in the payload. With sharing off, neither flag is set.
  • TestStubEligibility::test_a_vault_reference_is_not_skipped_for_its_env: with sharing on and a verdict of stub=True, share=False, the eligibility check accepts a vault-secret server.
  • TestStubEligibility::test_a_shared_declaration_keeps_the_share_bar: the same server also declared with no env pools, so it still needs recommend_share.
  • McpManagement.test.tsx › reads a private backend as stub, not shared, with sharing on: the row shows the state_stub label and no state_shared label.
  • McpManagement.oneStep.test.tsx › says in Details why a server on a backend of its own while sharing is on is in its state: Details shows why_private_backend. Fails with the detailsWhyKey hunk reverted.

Proof: PROVEN test/test_handlers_mcp_coverage_gateway_servers.py::TestGatewayServers::test_a_vault_reference_gets_a_private_backend_not_direct_env, test/test_handlers_mcp_coverage_gateway_servers.py::TestStubEligibility::test_a_vault_reference_is_not_skipped_for_its_env, test/test_handlers_mcp_coverage_gateway_servers.py::TestStubEligibility::test_a_shared_declaration_keeps_the_share_bar (head f2fa5f9)

Determinism: the new tests ran 20/20 at -n0 and 10/10 at -n 2 --dist loadgroup --max-worker-restart=2 with test_mcp_shareability.py and test_mcp_handler_facade.py as co-tenants. The whole file ran green (64 passed) in a shuffled order, seed 24918. The frontend test fails with the mcpManagementModel.ts hunk reverted.

Manual verification

Rendered the built SPA against a stubbed API with sharing on (screenshot below). The vault-secret row reads stub. The plain-env row still reads direct (env), and a plain stubbed row still reads shared. A live gateway was not run. The screenshot predates the rebase onto #19661, which relabels the English state_stub and state_direct_env chips to direct; the states themselves are unchanged.

Screenshots / video

MCP Management with a vault-secret row reading stub

Related Issues

Part of #24555

Sibling sweep

Swept: git grep -n "_withheld_env_count(" -- src/ website/src/
Sibling: src/kiro_crew/dashboard/handlers/mcp_gateway_routes.py -- changed here
Sibling: src/kiro_crew/dashboard/handlers/mcp_gateway_stubs.py -- changed here
Sibling: src/kiro_crew/mcp_gateway/rewriter_spec.py -- not affected -- already pairs the count with _needs_private_backend

Pattern harvest

Rule candidate: review-prompt
Pattern: a display or eligibility check that re-derives a decision from one of the decider's predicates, and misses the exception the decider applies on top of it.

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

@JLargent42
JLargent42 requested review from a team and KiroCrewCaptain as code owners October 27, 2026 16:49
@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)

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

Design-Verdict: PASS

cannot evaluate: missing a screenshot of the MCP Management row for a vault-secret server with sharing on. The description's image did not download, and this revision commits no image.

Blockers

Missing rendered evidence for the changed MCP Management row state and Details reason
Trigger: a stubbed row with "private_backend": true now goes through "if (s.stub && s.private_backend === true) return 'stub'" in mcpManagementModel.ts. Its Details reason is the new "why_private_backend" string.
Outcome: the evidence file lists 0 downloaded attachments and 0 committed images → no one can check how the new state chip and Details copy look next to the "shared" and "direct (env)" rows → the reshaped panel reaches users unseen. By the description's own account ("The screenshot predates the rebase onto #19661, which relabels … state_stub"), the screenshot was not of this revision anyway.
Fix: render the built SPA at this head with sharing on, showing one vault-secret row, one plain-env row and one plain stubbed row, plus the vault-secret row's Details. Attach it as a github.com/user-attachments image or commit it under temp-screenshots/.
Clears when: the evidence list for this revision names a downloaded or committed image that shows the vault-secret row's state chip and its "why_private_backend" Details text at head f2fa5f92 or later.

[DESIGN-REVIEWED] f2fa5f9

Description read

[DESCRIPTION-READ] b826eeb156f936e3e109c65ab0be3f24252078b9d47183361feab7095f1e4b02

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 Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of f2fa5f92e43cf0bfa29a1a7033c3e7209efd5c24 — 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

Each item fixes the row and eligibility check where they disagreed with the rewriter's vault-secret exception, using the rewriter's own two predicates. Nothing blocks.

What this change ships

Inventory (6 items) — 6 justified

Intent: let a user with sharing on see that a secret:// env server can be routed through the gateway, and approve its stub. FIX.

  1. A vault-secret server row no longer reads direct (env); pooling_blocked_by_env is false for it — justified
  2. The gateway servers payload gains a private_backend flag — justified
  3. A stubbed vault-secret row reads stub, not shared, while sharing is on — justified
  4. The Details panel gives a new reason, why_private_backend, added to every locale catalog — justified
  5. Stub eligibility stops skipping a vault-secret server for its env, and judges it on recommend_stub, not recommend_share — justified
  6. Rows now record env names per declaration, with vault-reference key names (no values), and _env_pooling_outcome is shared by both handlers — justified

[FIRST-PRINCIPLES-REVIEWED] f2fa5f9

Description read

[DESCRIPTION-READ] 9f638a4987ad2e87c9c0cbeb095cc2bb696be6bf19bd375f2a27616de1053266

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 Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)

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

UX-Verdict: PASS

cannot evaluate: missing a screenshot of the vault-secret row's new state chip and its Details reason. The description's image was removed and none is committed, so the blind read did not run.

Evidence gaps

  • State chip on a vault-secret (secret://) server row with sharing on. It now shows state_stub instead of direct (env), and no screenshot shows it. To close: attach a still of the MCP Management list showing this row next to a plain-env row and a shared row. Take it after the feat(mcp-gateway): share an MCP server with one labelled switch #19661 rebase, because the English chip labels changed there and the description says its screenshot is older than that.
  • Details reason why_private_backend. The new string is "Its env names a vault secret, so each chat keeps its own copy." and no screenshot shows it. To close: attach a still of the open Details panel for that row.

Notes

  • why_private_backend: "env" and "vault secret" are terms from the code, not words a user would know. Try "This server uses a saved secret, so each chat starts its own copy." and check it against what the blind reader understands once a screenshot is attached.

[UX-REVIEWED] f2fa5f9

Description read

[DESCRIPTION-READ] 5f6aff6dc867558d4590c23f5467cad505978df6f60c20c200fa41de3344c1ba

That sha256 names everything this verdict read: the PR description, plus the 3 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 Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] f2fa5f9

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

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

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 6.1 flagged blocking issues on f2fa5f92e43cf0bfa29a1a7033c3e7209efd5c24; Opus 5.5 adjudication downgraded every one of them. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents.

This comment is updated in place on each push.

Review details

BLOCKING -- src/kiro_crew/dashboard/handlers/mcp_gateway_routes.py:524 -- Include settings-injected declarations before marking a server private

private = bool(decls)
Trigger: With sharing on, forwarding off and the stub approved, declare the same server and command with a vault reference in Crew’s MCP config and without env in Kiro-global settings. A user-level agent with empty mcpServers and settings inheritance receives the env-less declaration through rewrite_agents → _injectable_settings_servers → _rewrite_single_spec, but _collect_server_rows records only the explicit private declaration.
Outcome: The inheriting agent gets a pooled backend, yet the endpoint returns private_backend: true; rowState reports it as unshared and Details incorrectly tells the operator that every chat keeps its own copy.
Anchor: defect
Fix: Include effective settings-injected declarations, respecting exclusions and name shadowing, before deciding that every declaration is private.

[BLOCK-MERGE-DOWNGRADED] f2fa5f9
[GPT-REVIEWED] f2fa5f9

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 is a LOW harm finding: a status label on the dashboard is wrong. Nothing about governance, credentials or data is affected. Conditions I checked: _collect_server_rows reads only ~/.kiro/agents/*.json (src/kiro_crew/dashboard/handlers/mcp_gateway_routes.py:411-440) and never the settings mcpServers that _injectable_settings_servers injects (src/kiro_crew/mcp_gateway/rewriter_spec.py:841-930). So private = bool(decls) (mcp_gateway_routes.py:524) counts only explicit declarations. The finding also needs four things together: sharing on, forwarding off, the same server name declared with a vault reference in an agent spec and without env in Kiro-global settings, and an inheriting agent whose mcpServers is empty.
What happens: the runtime does the right thing. The env-less settings entry is pooled and holds no secret, because the predicate at rewriter_spec.py:930 passes. The only effect is that private_backend / the Details text (mcp_gateway_routes.py:681) misstates sharing for that row. Nothing corrects it automatically, but the operator can see the row.
Fix cost: the row scan would need its own copy of the rewriter's settings-injection rules (stub membership, mute and registry exclusions, includeMcpJson, name shadowing). That is a second writer of the same decision for every future reader to keep in sync. That cost is larger than a rare, display-only mislabel.

[ADJUDICATION] f2fa5f92e43cf0bfa29a1a7033c3e7209efd5c24 total=1 uphold=0 downgrade=1
DOWNGRADE F1 src/kiro_crew/dashboard/handlers/mcp_gateway_routes.py:524 reason=disproportionate-remedy
[GPT-ADJUDICATED] f2fa5f92e43cf0bfa29a1a7033c3e7209efd5c24

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

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 27, 2026
@JLargent42
JLargent42 force-pushed the fix/24555-vault-env-routable-row branch from 1dcf5d6 to 7ab8a8f Compare October 27, 2026 17:03
@JLargent42

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: stub eligibility picks the share bar from the global sharing switch alone

  • span=b33a8f6bd401 batch stub judged a private-backend server on recommend_share

fixed in 7ab8a8f: _stub_eligibility keeps the private result of _env_pooling_outcome; a server whose every declaration gets a private backend has no co-tenants, so with sharing on it is judged on recommend_stub.
A name that also has a pooling declaration keeps the recommend_share bar.
Tests: test_a_vault_reference_is_not_skipped_for_its_env now uses stub=True, share=False and fails without the fix; test_a_shared_declaration_keeps_the_share_bar pins the mixed case.
Swept recommend_share call sites: seed.py adds stubs on recommend_stub already; the assessment chip only colours a label.

@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 Oct 27, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 27, 2026
@JLargent42
JLargent42 force-pushed the fix/24555-vault-env-routable-row branch from 7ab8a8f to 20bd750 Compare October 28, 2026 17:37
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 28, 2026
The MCP Management rows and the stub eligibility check counted every
declared env key a shared backend would withhold and reported the server
as `direct (env)`. The rewriter makes one exception: a declaration whose
env names a vault secret gets a connection-private backend the gateway
starts. The row now asks the rewriter's own two predicates per
declaration, reports that case as `private_backend`, and the page shows
it as `stub` rather than `direct (env)` or `shared`. The eligibility
check no longer skips it.

Part of #24555
@JLargent42
JLargent42 force-pushed the fix/24555-vault-env-routable-row branch from 20bd750 to f2fa5f9 Compare October 28, 2026 18:46
@JLargent42

Copy link
Copy Markdown
Contributor Author

AI review disposition: Opus 5.5 on 20bd750

BLOCKING, website/src/pages/settings/mcpManagementModel.ts (detailsWhyKey, 'stub' case): fixed in f2fa5f9.

A row with private_backend: true now gets the Details reason why_private_backend ("Its env names a vault secret, so each chat keeps its own copy.") instead of why_stub_off. Any other stub row still gets why_stub_off, which only shows while sharing is off. The new key is in en.manual.json, all eleven translated catalogs and the regenerated en-XA.json.

Test: McpManagement.oneStep.test.tsx, a new case in says in Details why %s is in its state with sharing on and private_backend: true. It fails with the detailsWhyKey hunk reverted and passes with it.

Local checks on the new head: vitest 153 passed across 7 MCP Management test files, catalogParity.test.ts 77 passed, npm run i18n:check, tsc and eslint clean. pytest -n 2 over 14 targeted files: 598 passed. prove.py PROVEN.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Oct 28, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This PR makes the MCP Management row and the batch stub check follow the rewriter's vault-secret exception. A server whose env names a secret:// value, with sharing on and forwarding off, now reports private_backend instead of pooling_blocked_by_env, so it is no longer shown as direct (env) and can be stubbed. It is scoped as part of #24555, and that issue's KAS env relay and warnings stay open by design.

Verified: _env_pooling_outcome calls the rewriter's own _withheld_env_count and _needs_private_backend (rewriter_env.py) per declaration, which matches the withheld and not private branch in rewriter_spec.py. Only key names reach the payload, and the test asserts the secret value is absent. The new backend tests fail without the fix (the vault row was blocked before). The mixed and env-less cases match the rewriter.

Duplicate check: no other open or merged PR covers this. Main has no private_backend handling. #19661 is merged and this PR is rebased on it. Mergeable on main.

Findings: 0 blocking, 1 suggestion. The settings-injected declaration case was already raised by GPT and downgraded, so it is not repeated here.

Good: the decider's predicates are reused instead of re-derived, and the description's sibling sweep is concrete.

AI-assisted review (Kiro), posted for bolichen.

allowed = verdict.recommend_share if sharing_on else verdict.recommend_stub
# A server every declaration of which gets a connection-private backend
# has no co-tenants even with sharing on, so the stub bar applies to it.
allowed = verdict.recommend_share if sharing_on and not private else verdict.recommend_stub

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 suggestion: Once a vault-secret server passes here on recommend_stub, will turning page-wide sharing on also add it to stub_servers through autoShareCandidates (mcpManagementModel.ts)? That helper offers every row whose pooling_blocked_by_env !== true, and its docstring says it picks only servers that can share. A private-backend server does not share. Moving it onto the gateway is probably the right outcome, since the session cannot resolve secret:// anyway. If that is intended, could the PR description and the autoShareCandidates docstring say so? If it is not, the filter could also skip private_backend === true. Rule: reviewer preference (the description should match the diff's behavior).

@bolichen97
bolichen97 merged commit 3f5c2eb into main Oct 29, 2026
176 of 185 checks passed
@bolichen97
bolichen97 deleted the fix/24555-vault-env-routable-row branch October 29, 2026 01:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants