feat(mcp): add shared bundled runtime scope by yu-xin-c · Pull Request #95591 · openclaw/openclaw

yu-xin-c · 2026-06-21T16:18:35Z

What Problem This Solves

Fixes #95506. Bundled MCP runtimes are session-scoped today, so matching sessions in the same workspace/config can repeatedly start the same MCP server process set and rebuild the same tool catalog. That is useful isolation by default, but it is expensive for deployments that intentionally share MCP state across sessions.

Why This Change Was Made

This adds an opt-in mcp.runtimeScope config with the default preserved as session. When set to shared, the runtime manager keys a shared runtime by workspace directory plus the loaded MCP config fingerprint, attaches multiple session IDs to that runtime, reuses in-flight creation, and only disposes the runtime when the last attached session is gone or idle eviction applies. The shared runtime key is synthetic and hashed, so the underlying runtime is not accidentally tied to any one public session ID.

User Impact

Existing configurations keep per-session isolation. Users who opt into mcp.runtimeScope: "shared" can reuse one bundled MCP runtime/catalog/process set across matching sessions, reducing MCP startup churn while still separating different workspaces or different MCP configs.

Evidence

node scripts/run-vitest.mjs src/agents/agent-bundle-mcp-runtime.test.ts passed: 40 tests, including real stdio MCP proof that default session scope starts two server processes/list calls for two sessions while shared scope reuses one runtime/server process/list call.
node scripts/run-vitest.mjs src/config/schema.test.ts src/config/schema.hints.test.ts src/config/schema.help.quality.test.ts src/config/doc-baseline.test.ts src/config/doc-baseline.integration.test.ts passed: 2 shards, 31 tooling tests + 62 runtime-config tests.
corepack pnpm config:docs:check passed.
corepack pnpm tsgo:core passed.
git diff --check passed.
2026-06-24 maintenance rebase on af2b0a611: re-ran node scripts/run-vitest.mjs src/agents/agent-bundle-mcp-runtime.test.ts (44 tests), node --import tsx scripts/generate-config-doc-baseline.ts --check, corepack pnpm tsgo:core, and git diff --check; all passed.
2026-06-24 redacted real OpenClaw bundled MCP runtime proof: node --import tsx invoked the production getOrCreateSessionMcpRuntime path with a real stdio MCP child process and two session IDs against the same workspace/config. Redacted terminal output:

OpenClaw bundled MCP runtime proof
SCENARIO session
  runtime-object-reused=false
  runtime-a-session-id=session-session-a
  runtime-b-session-id=session-session-b
  catalog-a-tools=proofProbe/session_proof_tool
  catalog-b-tools=proofProbe/session_proof_tool
  server-start-count=2
  initialize-count=2
  tools-list-count=2
  unique-server-pids=58563,58564
SCENARIO shared
  runtime-object-reused=true
  runtime-a-session-id=__mcp_shared__:64f722c66ec671d10b9cad14
  runtime-b-session-id=__mcp_shared__:64f722c66ec671d10b9cad14
  catalog-a-tools=proofProbe/shared_proof_tool
  catalog-b-tools=proofProbe/shared_proof_tool
  server-start-count=1
  initialize-count=1
  tools-list-count=1
  unique-server-pids=58572

corepack pnpm tsgo:test:src was attempted locally but produced no diagnostics and was interrupted after several minutes; not counted as passing evidence.

clawsweeper · 2026-06-21T16:20:15Z

Codex review: needs maintainer review before merge. Reviewed June 26, 2026, 9:52 AM ET / 13:52 UTC.

Summary
The PR adds opt-in mcp.runtimeScope: "shared" runtime reuse by workspace/config fingerprint, plus config/docs/schema metadata, SDK surface budget updates, and focused runtime tests.

PR surface: Source +162, Tests +434, Docs +14, Generated 0, Other 0. Total +610 across 12 files.

Reproducibility: yes. source-level: current main and the latest release still key bundled MCP runtimes by session id, while the PR body provides real stdio terminal proof that default session scope starts separate processes/list calls and shared scope reuses one runtime/process/list call.

Review metrics: 2 noteworthy metrics.

Config Surface: 1 added (mcp.runtimeScope). The new option changes bundled MCP runtime reuse and isolation semantics for operators who enable it.
Plugin SDK Public Surface Budgets: 3 increased (config-types, publicExports, publicDeprecatedExports). The new MCP config type reaches the plugin SDK public surface budget, so maintainers should confirm that exposure is intentional.

Stored data model
Persistent data-model change detected: persistent cache schema: src/config/schema.help.ts, serialized state: src/agents/agent-bundle-mcp-runtime.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #95506
Summary: This PR is a candidate implementation for the canonical identical workspace/config bundled MCP runtime fan-out issue; the older shared-runtime PR overlaps the same root cause but is not a merged or clean replacement.

Members:

canonical: MCP runtimes duplicate stdio sessions for identical workspace/config #95506 - The issue narrowly tracks duplicate bundled MCP runtimes, duplicate stdio sessions, and duplicate tools/list work for identical workspace/config sessions.
same_root_cause: perf(mcp): cache immutable bundled config discovery #79882 - The PR implements the same opt-in shared-runtime direction but remains open and conflicting, so it is related evidence rather than a safe superseding merge target.
superseded: [codex] feat(mcp): share bundled runtime scope and fix preflight compaction abort #95563 - The combined draft was closed unmerged after this narrower PR took over the MCP shared-runtime portion.
partial_overlap: [Performance]: Session switch blocks on synchronous MCP tool materialization (getCatalog + createRuntime) - 5-8s delay per switch #89408 - The issue includes session-scoped MCP materialization cost but also covers broader session-switch latency and lazy materialization choices.
partial_overlap: Gateway lazy-spawns duplicate stdio MCP children with identical ppid+config (memory + CPU leak) #75621 - The issue reports duplicate stdio MCP children and process pressure, but includes leak and reap behavior beyond the opt-in sharing contract here.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P2] Have maintainers explicitly accept or reject the opt-in shared MCP boundary and choose this branch versus perf(mcp): cache immutable bundled config discovery #79882.

Risk before merge

[P1] The new mcp.runtimeScope option is an operator-facing openclaw.json and plugin SDK config type surface that maintainers need to intentionally accept.
[P1] When enabled, shared mode lets MCP clients, child processes, catalog state, server-side state, and failure/backoff state cross the current per-session boundary.
[P1] A shared MCP child process, catalog load, hang, crash, or failure backoff can affect every attached matching session until detach, last-session disposal, config reload disposal, or idle eviction.
[P1] The same-direction PR at perf(mcp): cache immutable bundled config discovery #79882 is still open but conflicting, so maintainers need to choose one canonical landing path.

Maintainer options:

Accept The Opt-In Shared Boundary
Maintainers can intentionally accept shared MCP reuse for trusted single-tenant deployments while owning the cross-session client, process, catalog, server-state, and failure-state behavior.
Choose One Canonical Branch
If maintainers prefer this branch, close or supersede perf(mcp): cache immutable bundled config discovery #79882 after preserving useful proof; otherwise port this branch's reattach/tests/docs work into the chosen implementation.
Pause If Isolation Should Stay Strict
If bundled MCP clients must remain per-session only, pause or close both shared-runtime PRs and keep the current isolation model.

Next step before merge

[P2] Human maintainer review is needed for the new config/security boundary and canonical branch choice; no narrow automated repair is identified.

Security
Needs attention: No supply-chain issue was found, but the opt-in shared mode intentionally changes the MCP session isolation boundary.

Review details

Best possible solution:

Land one maintainer-approved shared-runtime implementation with session as the default, current reattach/stdio/idle/docs coverage preserved, exact-head validation complete, and an explicit branch choice versus #79882.

Do we have a high-confidence way to reproduce the issue?

Yes, source-level: current main and the latest release still key bundled MCP runtimes by session id, while the PR body provides real stdio terminal proof that default session scope starts separate processes/list calls and shared scope reuses one runtime/process/list call.

Is this the best way to solve the issue?

Unclear as a final product choice. Workspace/config-keyed sharing in the runtime manager is the right implementation layer for the fan-out, but the best merge path requires maintainer acceptance of the new config/security boundary and the canonical branch choice versus #79882.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 1cd6f81a46ae.

Label changes

Label justifications:

P2: This is a bounded opt-in MCP performance and resource-pressure feature with source-level evidence, but it touches config and runtime lifecycle boundaries.
merge-risk: 🚨 compatibility: The PR adds mcp.runtimeScope and changes bundled MCP lifecycle semantics for users who enable shared mode.
merge-risk: 🚨 security-boundary: Shared mode intentionally lets MCP client and child-process state cross the current per-session runtime boundary.
merge-risk: 🚨 availability: A shared MCP process, catalog load, hang, crash, or failure backoff can affect every attached matching session.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The PR body includes redacted terminal output from a real stdio MCP child through the production runtime path, showing default session isolation and shared-mode reuse after the fix.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes redacted terminal output from a real stdio MCP child through the production runtime path, showing default session isolation and shared-mode reuse after the fix.

Evidence reviewed

PR surface:

Source +162, Tests +434, Docs +14, Generated 0, Other 0. Total +610 across 12 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	5	226	64	+162
Tests	2	439	5	+434
Docs	3	23	9	+14
Config	0	0	0	0
Generated	1	2	2	0
Other	1	3	3	0
Total	12	693	83	+610

Security concerns:

[medium] Shared MCP runtime crosses session isolation — src/agents/agent-bundle-mcp-runtime.ts:1203
When mcp.runtimeScope is shared, matching sessions can attach to one MCP runtime and child-process set, so MCP clients, catalog state, server-side state, and failure/backoff state can cross session boundaries for users who enable it.
Confidence: 0.9

What I checked:

AGENTS policy read: Root AGENTS.md and scoped guides for agents, docs, scripts, tests, and plugin SDK were read; their compatibility-sensitive config/API and owner-boundary review guidance applies to this PR. (AGENTS.md:1)
Current main behavior: Current main still stores bundled MCP runtimes, in-flight creation, idle TTLs, and session-key lookup by session id, so matching workspace/config sessions do not share runtime ownership today. (src/agents/agent-bundle-mcp-runtime.ts:985, 1cd6f81a46ae)
PR runtime implementation: The PR resolves shared scope, hashes a synthetic shared runtime key, tracks session attachments per runtime key, and reuses in-flight creation for matching shared runtimes. (src/agents/agent-bundle-mcp-runtime.ts:1176, 6c321cedbe00)
PR coverage: Added tests cover default per-session separation, real stdio shared reuse, workspace/config fingerprint separation, creation failure cleanup, shared reattach, and active-lease idle eviction. (src/agents/agent-bundle-mcp-runtime.test.ts:1401, 6c321cedbe00)
Config and docs surface: The PR adds McpRuntimeScope, strict zod validation for mcp.runtimeScope, and docs warning that shared mode is for trusted single-tenant deployments because MCP process and failure state can cross sessions. Public docs: docs/gateway/configuration-reference.md. (docs/gateway/configuration-reference.md:175, 6c321cedbe00)
Release/current-main check: Latest release v2026.6.10 still exposes only servers and sessionIdleTtlMs in McpConfig and still uses session-id runtime creation, so the shared runtime scope is new PR behavior, not shipped or already on main. (src/config/types.mcp.ts:80, aa69b12d0086)

Likely related people:

steipete: Authored MCP operability work that substantially touched the runtime manager, config types, and gateway configuration docs this PR extends. (role: feature-history contributor; confidence: high; commits: 99ce71ddbbdb, 38d3d11cbc0c; files: src/agents/agent-bundle-mcp-runtime.ts, src/config/types.mcp.ts, docs/gateway/configuration-reference.md)
mmyzwl: Authored the recent merged bundle-tools latency PR touching the same runtime manager and runtime tests. (role: recent runtime contributor; confidence: high; commits: a2725b6a24c8; files: src/agents/agent-bundle-mcp-runtime.ts, src/agents/agent-bundle-mcp-runtime.test.ts)
vincentkoc: Recently updated plugin SDK surface budgets adjacent to this PR's public config type exposure and appears as a co-author on recent MCP runtime latency work. (role: recent area contributor; confidence: high; commits: 3ab7a7276492, a2725b6a24c8; files: scripts/plugin-sdk-surface-report.mjs, src/agents/agent-bundle-mcp-runtime.ts)
openperf: Authored the MCP lease-release idle-eviction fix whose active-lease and TTL invariants the shared-runtime path must preserve. (role: recent lifecycle contributor; confidence: medium; commits: f2530de8320e; files: src/agents/agent-bundle-mcp-runtime.ts, src/agents/agent-bundle-mcp-runtime.test.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

yu-xin-c · 2026-06-24T12:20:23Z

@clawsweeper re-review

clawsweeper · 2026-06-24T12:20:26Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

yu-xin-c · 2026-06-24T12:29:45Z

@clawsweeper re-review

clawsweeper · 2026-06-24T12:29:48Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

yu-xin-c · 2026-06-24T12:40:50Z

@clawsweeper re-review

yu-xin-c · 2026-06-24T18:08:17Z

@clawsweeper re-review

clawsweeper · 2026-06-24T18:08:20Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

yu-xin-c · 2026-06-24T18:31:37Z

@clawsweeper re-review

clawsweeper · 2026-06-24T18:31:40Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

yu-xin-c · 2026-06-25T14:04:43Z

@clawsweeper re-review

clawsweeper · 2026-06-25T14:04:47Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

yu-xin-c · 2026-06-25T14:08:40Z

@clawsweeper re-review

clawsweeper · 2026-06-25T14:08:44Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

yu-xin-c · 2026-06-25T14:20:26Z

@clawsweeper re-review

yu-xin-c · 2026-06-26T13:41:48Z

@clawsweeper re-review

clawsweeper · 2026-06-26T13:41:52Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

openclaw-barnacle · 2026-07-11T04:26:42Z

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

openclaw-barnacle · 2026-07-19T04:35:06Z

Closing due to inactivity.
If you believe this PR should be revived, post in #clawtributors on Discord to talk to a maintainer.
That channel is the escape hatch for high-quality PRs that get auto-closed.

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime agents Agent runtime and tooling size: L labels Jun 21, 2026

yu-xin-c mentioned this pull request Jun 21, 2026

[codex] feat(mcp): share bundled runtime scope and fix preflight compaction abort #95563

Closed

openclaw-barnacle Bot added the triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. label Jun 21, 2026

openclaw-barnacle Bot removed the triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. label Jun 21, 2026

clawsweeper Bot mentioned this pull request Jun 21, 2026

perf(mcp): cache immutable bundled config discovery #79882

Merged

15 tasks

yu-xin-c changed the title ~~[codex] feat(mcp): add shared bundled runtime scope~~ feat(mcp): add shared bundled runtime scope Jun 23, 2026

yu-xin-c force-pushed the codex/95506-mcp-shared-runtime branch from 7c3e8d9 to b9cd27f Compare June 23, 2026 15:18

clawsweeper Bot added the merge-risk: 🚨 availability 🚨 May cause crashes, hangs, restart loops, stalls, or process outages. label Jun 24, 2026

yu-xin-c force-pushed the codex/95506-mcp-shared-runtime branch from b9cd27f to 4dda92b Compare June 24, 2026 12:29

yu-xin-c marked this pull request as ready for review June 24, 2026 13:07

clawsweeper Bot removed the rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. label Jun 24, 2026

clawsweeper Bot added the rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. label Jun 24, 2026

yu-xin-c force-pushed the codex/95506-mcp-shared-runtime branch 2 times, most recently from ac88c99 to b221481 Compare June 24, 2026 17:56

yu-xin-c force-pushed the codex/95506-mcp-shared-runtime branch from b221481 to f86e61a Compare June 24, 2026 18:22

yu-xin-c force-pushed the codex/95506-mcp-shared-runtime branch from d885b22 to eff2e30 Compare June 25, 2026 14:08

clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. labels Jun 25, 2026

yu-xin-c added 6 commits June 26, 2026 21:31

feat(mcp): add shared bundled runtime scope

4225839

fix(mcp): avoid shared runtime lint shadow

af3637d

test(mcp): update plugin sdk surface budget

0df00bc

test(sdk): satisfy surface report regex lint

0cb983e

fix(mcp): preserve session keys on runtime reattach

16623b7

test(sdk): refresh surface export budget

6c321ce

yu-xin-c force-pushed the codex/95506-mcp-shared-runtime branch from eff2e30 to 6c321ce Compare June 26, 2026 13:41

clawsweeper Bot mentioned this pull request Jun 26, 2026

Gateway lazy-spawns duplicate stdio MCP children with identical ppid+config (memory + CPU leak) #75621

Closed

openclaw-barnacle Bot added the stale Marked as stale due to inactivity label Jul 11, 2026

openclaw-barnacle Bot closed this Jul 19, 2026

Uh oh!

Uh oh!

Conversation

yu-xin-c commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yu-xin-c commented Jun 24, 2026

Uh oh!

clawsweeper Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yu-xin-c commented Jun 24, 2026

Uh oh!

clawsweeper Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yu-xin-c commented Jun 24, 2026

Uh oh!

yu-xin-c commented Jun 24, 2026

Uh oh!

clawsweeper Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yu-xin-c commented Jun 24, 2026

Uh oh!

clawsweeper Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yu-xin-c commented Jun 25, 2026

Uh oh!

clawsweeper Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yu-xin-c commented Jun 25, 2026

Uh oh!

clawsweeper Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yu-xin-c commented Jun 25, 2026

Uh oh!

yu-xin-c commented Jun 26, 2026

Uh oh!

clawsweeper Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openclaw-barnacle Bot commented Jul 11, 2026

Uh oh!

openclaw-barnacle Bot commented Jul 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

yu-xin-c commented Jun 21, 2026 •

edited

Loading

clawsweeper Bot commented Jun 21, 2026 •

edited

Loading

clawsweeper Bot commented Jun 24, 2026 •

edited

Loading

clawsweeper Bot commented Jun 24, 2026 •

edited

Loading

clawsweeper Bot commented Jun 24, 2026 •

edited

Loading

clawsweeper Bot commented Jun 24, 2026 •

edited

Loading

clawsweeper Bot commented Jun 25, 2026 •

edited

Loading

clawsweeper Bot commented Jun 25, 2026 •

edited

Loading

clawsweeper Bot commented Jun 26, 2026 •

edited

Loading