Summary

Closes T2.8 from issue #4514. Adds a pair of mutate-gated HTTP routes that mutate the daemon's runtime MCP server registry without requiring a daemon restart.

• POST /workspace/mcp/servers — add or replace a runtime MCP server entry. Idempotent on same name (replaces existing). Reuses existing WorkspaceMcpBudget enforce/warn/off modes.
• DELETE /workspace/mcp/servers/:name — drop a runtime entry. Idempotent on missing names. If the name is also declared in settings.json, wasShadowingSettings: true informs the caller that the settings entry will return on restart.

Capability tag: mcp_server_runtime_mutation: { since: 'v1' } (always-on). Events: mcp_server_added and mcp_server_removed fan out to attached clients with originatorClientId stamping.

Tracking comment on issue: #4514 (comment)

Design rationale

• Ephemeral persistence: matches /restart semantics; daemon restart re-reads settings.json cascade. Consumers wanting durability edit settings.json themselves.
• Shadow over settings: POST overlays settings entries via runtime overlay map in Config.getMcpServers() cascade. DELETE drops the runtime overlay; settings entries return on restart.
• Idempotent replace: same name + same fingerprint = no spawn churn (pool-level dedup). Same name + different fingerprint = drain old + spawn new, both share budget slot transiently.
• Budget guard reuse: WorkspaceMcpBudget modes already model enforce / warn / off; replace doesn't consume new slot (same name).
• Active refs on DELETE: pool drain semantics (mark draining, do not block existing refs); differs from /restart's kill-respawn since DELETE has no respawn target.

Full design doc: docs/superpowers/specs/2026-05-26-t2.8-mcp-server-runtime-add-remove-design.md (on the polished-gathering-finch worktree branch — link to be added once that PR opens). Implementation plan: docs/superpowers/plans/2026-05-26-t2.8-mcp-server-runtime-add-remove.md.

Architecture

HTTP layer (server.ts POST/DELETE /workspace/mcp/servers/...)
       → HttpAcpBridge.{add,remove}RuntimeMcpServer (bridge.ts)
       → ACP ext-method qwen/control/workspace/mcp/runtime-{add,remove} (acpAgent.ts)
       → McpClientManager.{add,remove}RuntimeMcpServer (mcp-client-manager.ts)
       → Config runtime overlay + WorkspaceMcpBudget + McpTransportPool
       ← typed errors → RequestError(data.errorKind) → sendBridgeError mapping
       ← success → publishWorkspaceEvent(mcp_server_{added,removed})

Wire contract additions

• Routes: POST /workspace/mcp/servers, DELETE /workspace/mcp/servers/:name
• Events: mcp_server_added (replaced/shadowedSettings/toolCount), mcp_server_removed (wasShadowingSettings)
• Capability tag: mcp_server_runtime_mutation: { since: 'v1' }
• Error kinds: mcp_budget_would_exceed (409), mcp_server_spawn_failed (502, with exitCode/stderr/timeout in body), invalid_config (400)
• ACP ext-methods: qwen/control/workspace/mcp/runtime-add, qwen/control/workspace/mcp/runtime-remove
• SDK types: DaemonRuntimeMcpAddRequest, DaemonRuntimeMcpAddResult (discriminated union), DaemonRuntimeMcpRemoveResult (discriminated union), MCPServerConfigShape, DaemonMcpServerAddedData, DaemonMcpServerRemovedData
• SDK helpers: DaemonClient.addRuntimeMcpServer, DaemonClient.removeRuntimeMcpServer

Test plan

• npm run typecheck clean across sdk-typescript, core, acp-bridge, cli
• npm test --workspace packages/sdk-typescript — 653/653 pass
• npm test --workspace packages/acp-bridge — 305/305 pass
• npm test --workspace packages/core — T2.8 cases all green (1 unrelated anthropicContentGenerator flake)
• npm test --workspace packages/cli — T2.8 cases all green (a few unrelated flakes in auth/AuthDialog/useAtCompletion, not regressions)
• Lint clean on all touched source files
• CI lint/format/build
• Manual smoke (from spec; defer to reviewer):
  • Start daemon: qwen serve --port 18280 --token foo
  • POST stdio MCP server (e.g. npx -y @modelcontextprotocol/server-everything) → GET /workspace/mcp reflects it
  • POST same name with new command → response replaced: true
  • DELETE → GET /workspace/mcp clears
  • Restart daemon → settings entries return, runtime entries gone
  • 2 SSE consumers → POST → both receive mcp_server_added with originatorClientId
  • Budget --mcp-budget=2 --mcp-budget-mode=enforce + POST a 3rd → 409
  • Budget warn → 200 + mcp_guardrail_events
  • --require-auth + no token POST → 401

Backward compatibility

• New always-on capability tag — older SDKs ignore unknown keys
• New event types — asKnownDaemonEvent → undefined on older SDKs (additive, no protocol bump)
• Config.addMcpServers post-init guard unchanged; new addRuntimeMcpServer/removeRuntimeMcpServer use a separate runtimeMcpServers overlay map
• excludedMcpServers mechanism unchanged — runtime entries pass through isMcpServerDisabled like everything else

Commit history

15 TDD commits + 1 typecheck fix, mirroring the implementation plan:

1. 1bc24d784 feat(sdk): mcp_server_added event type
2. 5a88394c0 feat(sdk): mcp_server_removed event type
3. 64b7b1b52 feat(sdk): runtime MCP request + result types
4. 40a033079 feat(core): Config.addRuntimeMcpServer / removeRuntimeMcpServer
5. 3003fb9c3 docs(core): tighten Config.addRuntimeMcpServer JSDoc wording
6. 88b64cb62 feat(core): runtime MCP overlay in getMcpServers cascade
7. 878571bc3 feat(core): McpClientManager runtime add/remove + budget/pool wiring
8. fdfcbc970 feat(acp-bridge): T2.8 error kinds
9. 3fd0dfcfb feat(acp-bridge): qwen/control/workspace/mcp/runtime-{add,remove} ext-methods
10. 6cd691aef feat(acp-bridge): host-side {add,remove}RuntimeMcpServer + event fan-out
11. 7f338fcc2 feat(serve): POST /workspace/mcp/servers route
12. 4c6d0b205 feat(serve): DELETE /workspace/mcp/servers/:name route
13. 73388f347 feat(serve): mcp_server_runtime_mutation capability tag
14. 8d9eb82c8 feat(sdk): DaemonClient runtime add/remove helpers
15. 3a8f766d7 docs(serve): document runtime MCP routes
16. d31a2a8ac fix(test): index-signature property access

Tracking issue: #4514

🤖 Generated with Qwen Code

📝 描述准确性更新（2026-05-31，作者自查）

补充：运行时 add MCP 会静默剥离 env/headers/trust/cwd/oauth 等字段，需密钥/鉴权头的 MCP server 添加后不可用且无回传告警。