Skip to content

fix(agent): mount a dropped MCP server once its program is back - #35837

Merged
bolichen97 merged 1 commit into
mainfrom
fix/34969-retry-dropped-mcp
Nov 12, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/34969-retry-dropped-mcp

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An MCP server that was left out of the default agent because its program was missing comes back in the next chat once the program is installed, without a gateway restart.

When the gateway rebuilt ~/.kiro/agents/kirocrew.json while a server's program was briefly missing (for example npx during a Homebrew relink of node), the rebuild logged Dropping MCP server '<name>': command not found and wrote the spec without that server. Once the program was back, new chats still had none of the server's tools until kirocrew restart.

Why it matters

Agents told to use those tools stop or fall back to unmanaged work, and the only fix users find is restarting the gateway, which interrupts every running chat.

Not a goal

  • Resumed chats losing their servers (the issue's first trigger): fix(acp): carry brace globs and the 120 s MCP start budget on KAS resume #32602, merged after 0.12.1-rc.3, keeps user servers in the agent block on resume with the 120 s start budget. Not changed here.
  • Hand-adding @<server> to tools/allowedTools in kirocrew.json (the second trigger): the file is rebuilt from the MCP sources on every start by design, and Customize → Connections → MCP Servers is the supported path. Not changed here.
  • A program found only through the server's own env.PATH, or under a Node version installed after the gateway started (those directories are listed once per process): the server is still retried at the next gateway start or config change, and the docs say so.
  • The wording of the MCP tab's drop note, which still names a gateway restart as the fix.

What changed (motivation → approach → change)

A server dropped because its program was not found now comes back at the next chat on the default agent, once the program is installed. Before, the rebuild recorded the drop in mcp-dropped-servers.json and nothing read that record again: only a gateway start or a config change re-runs the rebuild, so the server stayed out of every session until a restart.

The self-heal that already runs before every default-agent session, ensure_agent_materialized in agent_parts/spec_rebuild.py, now also checks that record when kirocrew.json exists. If a recorded command is found on the search path the rebuild resolver uses, it runs rebuild_agent_config() once before the spawn and logs which servers came back. That rebuild mounts the server and clears its record, so the next session start finds nothing to do. With no record, the usual case, the self-heal returns as before.

src/kiro_crew/docs/agents.md, src/kiro_crew/docs/troubleshooting.md, docs/architecture/mcp.md and the module docstring of src/kiro_crew/mcp_dropped_servers.py say a dropped server is retried at the next session start, and when a restart is still needed.

Backwards compatibility

Compatible: an existing spec is rebuilt only when a recorded program now resolves, and that rebuild is the same one a gateway start runs; nothing main accepts is refused, renamed or removed.

Removes nothing: the diff only adds a rebuild trigger.

Tests

test/test_agent_spec_safety.py::test_ensure_agent_materialized_rebuilds_once_a_dropped_program_is_found: with a drop recorded and the program absent from PATH, a default-agent session start does not rebuild; once the program is on PATH, it rebuilds once. That the rebuild then mounts the server and clears the record is already locked in by test/test_mcp_dropped_servers.py::test_a_command_not_found_drop_is_recorded_and_shown_until_it_resolves.

The new test passes 20 times at -n0, 10 times at -n 4 --dist loadgroup beside test/test_agent_spec_safety.py and test/test_mcp_dropped_servers.py, and the two files pass in a shuffled order (seed 14007, 43 tests).

Proof: PROVEN test/test_agent_spec_safety.py::test_ensure_agent_materialized_rebuilds_once_a_dropped_program_is_found (head 360461a)

Manual verification

N/A — unit coverage sufficient: the change is one new branch in the pre-spawn self-heal, driven by the new test, and the rebuild it calls is the existing one the dropped-servers tests run end to end.

Related Issues

Closes #34969

Sibling sweep

Swept: git grep -nE "load_dropped|record_rebuild_drops" -- src/
Sibling: src/kiro_crew/agent_parts/spec_rebuild.py:1189 -- changed here
Sibling: src/kiro_crew/dashboard/handlers/mcp_probe.py:254 -- not affected -- it only reads the record to put a note on the server's row
Sibling: src/kiro_crew/agent_materialization/kiro_hooks.py:123 -- not affected -- a skipped hook is an absolute path the user wrote, never recorded, and not an MCP server

Pattern harvest

Not generalizable: the only drop that is recorded and then never re-read is the default-agent rebuild's command-not-found drop, and this is its one retry seam.

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

A server whose command was not found at a rebuild was left out of
kirocrew.json and recorded in mcp-dropped-servers.json, but nothing
re-ran the rebuild when the program came back: only a gateway start
or a config change does, so its tools stayed missing from every
session until a restart.

The pre-spawn self-heal for the default agent now also rebuilds an
existing spec when a recorded command resolves on the rebuild
resolver's search path. The rebuild mounts the server and clears the
record, so the check goes quiet again. Docs name the retry.

Closes #34969
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 12, 2026 12:38
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 12, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The retry runs inside the existing pre-spawn self-heal and reuses the gateway-start rebuild. It searches a subset of the path the resolver searches, so once a server is mounted the record clears and the check stops.

Notes

  • The record is refreshed only after write_default_spec succeeds (spec_rebuild.py:877). If a rebuild bails before that, through the declined path or _AgentSpecUnreadable, the record stays. Each default-agent spawn then runs a full rebuild_agent_config on the hot path for as long as the program resolves. Logging that once, or rate-limiting it, would keep a stuck case cheap.

[DESIGN-REVIEWED] 360461a

Description read

[DESCRIPTION-READ] 14a55876667884dd39725468d8ec3599f5f82aaa6f9a8a8f9e9102d58b3f3b67

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 360461acbba9230fc614b5d8ca1b82e811b8d7e9 — 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. The new step goes to the cause: the drop record had no reader that retried the rebuild. It reuses the existing rebuild and search path, and it runs only while a drop is on record.

What this change ships

Inventory (4 items) — 4 justified

Intent: a user who installs a missing MCP server's program gets that server's tools in their next chat without restarting the gateway. This is a FIX (#34969).

  1. Before each default-agent session starts, any server dropped as "command not found" whose program now resolves triggers a spec rebuild that mounts it again. — justified
  2. The gateway log gets a new INFO line naming the servers that came back. — justified
  3. agents.md and troubleshooting.md now say a new chat brings the server back, and say when a restart is still needed (env.PATH, a Node version installed later). — justified
  4. docs/architecture/mcp.md and the mcp_dropped_servers docstring now name the record's second reader. — justified

[FIRST-PRINCIPLES-REVIEWED] 360461a

Description read

[DESCRIPTION-READ] a241d2405bf21527c8f8ede0f98d2aaf9bcaacbc5de6beddead17ea7d0197144

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 360461acbba9230fc614b5d8ca1b82e811b8d7e9 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 360461a

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

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 360461a

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

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

@bolichen97
bolichen97 enabled auto-merge (squash) November 12, 2026 12:49
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 12, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

Adds a retry to the pre-spawn self-heal in ensure_agent_materialized. When a server recorded in mcp-dropped-servers.json as command-not-found now resolves, it runs rebuild_agent_config once. The check expands the recorded command the same way the resolver does, and searches mcp_search_path(""), which is always a subset of what the resolver searches for any server (the server's own env.PATH entries come first, then the shared ones). So a found program always gets mounted, and the rewritten record stops the check from firing again; it cannot loop. The recorded command is the winning entry's command, the first one the resolver tries. All async callers already run this function off the event loop. The new test fails without the change and passes on Windows CI.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 360461acbb · 88 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@buluoray buluoray 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.

Approve on 360461a. Before this change, an MCP server that a rebuild dropped because its program was missing stayed out of every new chat until a gateway restart. Now the pre-spawn self-heal reads the drop record, and when a recorded program is found on the search path the rebuild uses, it runs the normal rebuild once before the session starts. The rebuild then mounts the server and clears the record. The gate is a subset of the rebuild's own resolver: same argument expansion, same search path minus the server's own PATH entry. So a program that the gate finds is also found by the rebuild, and the retry fires once. While the program is still missing, the cost is one small file read and one path lookup per recorded server, with no rebuild. The retry runs the same rebuild as a gateway start, so it applies the same disabled flags, spec gate, governance and approval ceiling. It adds no approval and does not touch a user's own MCP files. A server that the person removed or turned off is not mounted by this path, because the rebuild decides what to mount from the current sources, exactly as at a restart. The new test fails both when the retry is taken out and when the missing-program check is taken out. All checks pass and every review lane on this head passed or was correctly skipped. Decisive lines: src/kiro_crew/agent_parts/spec_rebuild.py:1187-1206, src/kiro_crew/agent_parts/spec_rebuild.py:877-883, src/kiro_crew/agent_materialization/mcp_sources.py:1014-1016, src/kiro_crew/agent_materialization/mcp_sources.py:710-717, test/test_agent_spec_safety.py:71-97

@bolichen97
bolichen97 merged commit 7aaa5e9 into main Nov 12, 2026
98 checks passed
@bolichen97
bolichen97 deleted the fix/34969-retry-dropped-mcp branch November 12, 2026 14:37
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.

MCP server tools vanish after session resume, agent-spec change, or a missing command at start

3 participants