feat(harness): share MCP servers by scope and close idle ones - #83

Summary

Stacked on #81. Decides who shares a running MCP server and how long it lives. Until now every session ran its own servers until the process exited.

Scopes (scope in mcp.json, default session)

• When the sandbox isn't local, session and space servers start in hostDir, else hostCwd, and get no roots. MCP stays host-only.
• An instance is keyed by its scope plus everything its connection is made from (config minus exposure, cwd, roots). Sessions that resolve different settings for a server, for example through different project files, never share it.
• Exposure stays each session's own. Two sessions can share an instance and declare different tools.

Lifetime

• Each drain leases its session's instances for as long as it runs (runner/execute.ts, next to the mount).
• An instance no session uses closes at once, for example when a server is removed or its settings change.
• An instance no drain holds closes after an idle timeout: 10 minutes, or the Harness.layer option mcpIdleTimeout. The next exchange that needs it starts it again.
• Space changes need no hooks. After rehome or absorb, a session's next exchange resolves a different key and drops the old instance; an archived env's instances idle out.

Also

• A session's servers keep their config order across exchanges, so a restarted server's tools no longer move to the end of the list. That's more stable for prompt caching.
• Docs: "Sharing a Server" and idle close on the MCP page.

Review fixes (Codex, gpt-6.1-sol high)

• Name in the key. An instance key includes the server's name. Two entries with the same settings are two instances, and renaming a server can't close the instance its new name uses.
• Exact lease counts. Leases count each instance once per session, so an alias can't drive a count negative and keep a server from idling out.
• Atomic bookkeeping. Reconcile updates every membership and lease count in one step and closes unused instances on their own, so an interrupted exchange can't leave a shared instance counting a session it no longer has.
• Idle timer from the start. An instance created with no drain holding it still gets an idle timer.
• Canonical keys. Keys are canonical JSON, so the same env / headers in another order share an instance.
• Dismissed: a lease arriving mid-reconcile. The coordinator runs one drain per session, and reconcile runs inside it. The atomic bookkeeping removes the window anyway.
• Test: the scope test adds twin, a server with mine's exact settings. It runs as its own process, and everything still idles out.

Tagged errors

Every MCP failure is now a Schema.TaggedError (UnavailableError, ToolCallError, ResourceError, ValueError, OutputError; connect attempts use ConnectError), as opencode does. The tool adapter turns error.message into model text only at the edge. The model-facing text is unchanged, and no artifact moved.

Pi's exposure values

mcp.json accepts every exposure Pi does (direct, hidden, codemode, deferred, and codemode-deferred as an alias), so entries copied from Pi stay valid.

• Until codemode and tool_search exist, codemode / deferred tools aren't declared, and the session is warned once with Pi's wording.
• Resource tools are declared when a server with resources is direct, and reach every server with resources that isn't hidden.
• The default stays direct for now, and flips to codemode (Pi's default) with the codemode work.

CLI end-to-end

packages/codework/test/cli.mcp.test.ts spawns the real codework run with mcp.json, a fake OpenAI-compatible provider and a hand-written stdio MCP server. It checks that:

• the tool is declared with the server's schema
• the call's result reaches the model
• the server ran in the session's directory
• the server is gone after the CLI exits

Artifact: cli.mcp.json.

Test plan

• test/mcp.session.test.ts gets a new scope test, through the full harness with real stdio servers. Sessions A and B share a space and C is in another, each calling a session, a space and an app server:
  • session: three processes
  • space: A and B share one, C has its own
  • app: one process for all three
  • After the drains end, every instance idles out and its process is gone. A later run starts fresh instances.
  • Artifact: mcp.session.scopes.json, stable across runs.
• Lifecycle artifact: only the more stable tool order changed.
• Full harness suite: 525 passed, 34 skipped (live/remote)
• vp check and vp run typecheck

🤖 Generated with Claude Code