Skip to content

fix(mcp-gateway): share a bot worker's base mcp servers across bots - #36396

Closed
jingchaodev wants to merge 1 commit into
kirodotdev:mainfrom
jingchaodev:feat/bot-shared-mcp-overlays
Closed

jingchaodev wants to merge 1 commit into
kirodotdev:mainfrom
jingchaodev:feat/bot-shared-mcp-overlays

Conversation

@jingchaodev

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Bot workers on KAS share one gateway backend per stubbed base MCP server, the way chats do, instead of each starting its own copy.

Each Bot worker on KAS starts its own copy of every MCP server in the worker base spec, kirocrew-mate-worker: Kiro Crew's own five and every other base server. An ordinary chat gets broker stubs for the same servers, and since #34909 a Bot's chat does too. On one host on v0.12.2, with 9 workers running, that was 45 Kiro Crew server processes (9 copies of each of the 5) and 46 other server processes, about 16 GB RSS (#36260).

Why it matters

The cost is per worker: about 10 server processes and 1.4 GB RSS each on that host, so it grows with every Bot that hands work to a worker. A broker stub measured about 7 MB RSS on the same host. Most of that memory holds identical copies of the same servers.

Not a goal

What changed (motivation → approach → change)

Symptom → cause: mate_overlays.list_mate_sources skipped the worker spec, so the overlay pass wrote no overlay with stubs for its servers. worker_overlay_spec, a KAS worker's stub lookup, returned only the servers a Bot's own file adds. KAS therefore declared every base server per session, and a Bot with no file of its own got no stub at all.

Change, on top of #34909's approach for the conductor spec:

  • The crewmate half of the pass also rewrites kirocrew-mate-worker.json into <overlay dir>/mates/kirocrew-mate-worker.json, under the worker's own name rather than a crewmate: identity, since no Bot owns that file. Its stubs carry --agent kirocrew-mate-worker, the task profile the worker's own tool calls already get. A same-named ~/.kiro/agents spec blocks it like any identity collision.
  • worker_overlay_spec takes each base server's stub from that overlay and each added server's stub from the Bot's own, through the checks it already ran: the governed merged spec must still mount the server unmuted and not registry-governed, disabledTools is that spec's, and autoApprove is dropped. A Bot with no file gets the base stubs alone. An overlay carrying another name yields no stub.
  • _shared_by_every_worker keeps out a kirocrew-* server that is not a caller-aware managed one (_MANAGED_SERVERS_CALLER_AWARE), for example an edition's own server. Such a server may read KIROCREW_SESSION_KEY from its own process, which a shared backend leaves empty, so it still starts per session.

Why mates/ and not beside the conductor's overlay: claude and codex workers look stubs up by name, and that lookup would hand them the base stubs without the per-Bot mute and registry checks above. In mates/, only the KAS lookup reads it.

What is shared follows the pool key, which has no agent or principal dimension (mcp_gateway/pool.py). Every Bot of a gateway runs as that gateway's OS user, the os_uid partition its chats already share. The caller-aware servers read the caller from each call, so one backend keeps each Bot's memory and work apart.

docs/architecture/mcp.md ("Bot overlays") and docs/system-specs/modules/mcp-gateway-daemon-lifecycle.md describe the worker overlay.

#35833, now on main, relays the own servers' tool lists for a per-session copy and skips a pooled backend. With this change a KAS worker's own servers are pooled, so that relay no longer applies to them; each backend starts once instead. The branch merges with it cleanly.

Backwards compatibility

Compatible: the pass writes one more overlay, and a KAS worker gets broker stubs for the base servers in place of declaring them itself. Every other lookup returns what it returned before, and with mcp_gateway.enabled off each stub keeps a backend of its own.

Removes nothing: the change adds an overlay and a stub source; no key, record, validator or public function is removed or narrowed.

Tests

test/test_mcp_gateway_mate_overlays.py, new TestTheSharedWorkerOverlay (12 cases): the base servers' stubs carry the worker identity and a caller-unaware kirocrew-* server stays out; a Bot with no file gets the base stubs; a Bot file's server sits beside the base one under the Bot's identity; a base server the merged spec mutes is not injected; the stub is poolable only while pooling is on; a lookup without a KAS key never reads the overlay; an overlay with another name injects nothing; a same-named ~/.kiro/agents spec blocks it; the sharing rule for four kinds of server. Two existing tests now expect the worker spec as a source and as an overlay.

Proof: PROVEN test/test_mcp_gateway_mate_overlays.py::TestTheRewritePass::test_the_worker_spec_gets_one_overlay_under_its_own_name, test/test_mcp_gateway_mate_overlays.py::TestSkippedCrewmateSourcesReadAsAbsent::test_no_overlay_and_the_pass_stays_complete[file], test/test_mcp_gateway_mate_overlays.py::TestSkippedCrewmateSourcesReadAsAbsent::test_no_overlay_and_the_pass_stays_complete[off-record], test/test_mcp_gateway_mate_overlays.py::TestTheSharedWorkerOverlay::test_a_crewmate_file_adds_its_own_stub_beside_the_base_one (head ae73fd8)

Determinism: the file passed 20 runs at -n0, 10 runs at -n 4 --dist loadgroup --max-worker-restart=2 beside test/test_mcp_gateway_scope_mute.py and test/test_codex_crew_stub.py, and one run in a shuffled order (seed 24117).

Manual verification

Not run on a live gateway: a before and after count needs a KAS sign-in and Bots in a scratch home. The numbers above are measured on v0.12.2 before the change. The cost after it, one shared backend per stubbed base server plus about 7 MB per stub per worker, is an estimate from the stub size measured on the same host.

Related Issues

Closes #36260

Sibling sweep

Swept: git grep -nE "is_mate_service_agent(|MATE_SERVICE_AGENT_FILENAMES|worker_overlay_spec" -- src/
Sibling: src/kiro_crew/mcp_gateway/rewriter.py -- not affected -- the conductor spec already gets its overlay through with_conductor_source
Sibling: src/kiro_crew/acp/client_mcp_array.py -- not affected -- claude and codex workers resolve stubs by agent name and never read mates/; sharing there needs the mirrors' own per-Bot checks, outside this goal

Pattern harvest

Rule candidate: review-prompt
Pattern: a spec Crew writes outside ~/.kiro/agents (a Bot service spec) gets no gateway overlay, so its sessions start every stubbed server unpooled

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

Contributions are accepted under the project's Apache-2.0 license.

Each Bot worker on KAS started its own copy of every server in the
kirocrew-mate-worker base spec. The overlay pass wrote no overlay for
that spec, and the worker lookup returned only the servers a Bot's own
file adds, so a Bot with no file got no stub at all.

The crewmate half of the pass now also rewrites the worker spec into
mates/kirocrew-mate-worker.json under the worker's own name. The worker
lookup takes each base server's stub from it and each added server's
stub from the Bot's own overlay. A kirocrew-* server that does not read
its caller per call stays out of it and starts per session. Bot chats
already share through the conductor overlay.

Closes kirodotdev#36260
@jingchaodev
jingchaodev requested review from a team and KiroCrewCaptain as code owners November 13, 2026 04:30
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Nov 13, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This PR and #37695 fix the same defect: the overlay pass never writes stubs for the stock kirocrew-mate-worker.json, so each Bot worker session starts its own copy of the base MCP servers. Both change worker_overlay_spec and the overlay writer in src/kiro_crew/mcp_gateway/mate_overlays.py, plus test/test_mcp_gateway_mate_overlays.py and docs/architecture/mcp.md.

Please keep one of #36396 and #37695 and close the other, carrying over anything only this one has (for example, the Closes #36260 link and the _shared_by_every_worker exclusion).

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 16, 2026
@jingchaodev

Copy link
Copy Markdown
Contributor Author

This duplicates #37695, which merged on 2026-11-16 as f1b575f and fixes the same defect. Closing this one. Thanks @buluoray for the fix.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Each Bot worker starts its own copy of every base MCP server

2 participants