Build built-in MCP groundwork and on-demand server injection bridge #155

Activity

1. Juliusolsson05 commented on May 16, 2026

   

   Juliusolsson05

   on May 16, 2026

   OwnerAuthor

   More actions

   Implementation Plan After MCP + Repo Audit

   Relevant MCP facts

   • MCP tools are model-controlled; Agent Code must enforce scoping, limits, and user-visible lifecycle rules in code, not only in tool descriptions.
   • Stdio is the right first transport for built-in local servers.
   • Tool schemas should be tight and token-efficient. Prefer small structured results over transcript dumps.
   • Claude Code supports dynamic MCP injection through --mcp-config <json-or-file> and --strict-mcp-config.
   • Codex supports MCP servers under mcp_servers config. Its config type accepts stdio fields: command, args, env, env_vars, cwd, plus startup_timeout_sec, tool_timeout_sec, enabled_tools, and disabled_tools.
   • Agent Code already spawns Claude/Codex through provider wrappers, so per-session MCP config belongs in SessionManager.spawn -> provider options -> provider argv/env.

   Repo integration points

   • src/main/sessionManager.ts

     • Extend SpawnOptions with something like mcpDomains?: BuiltInMcpDomain[] or mcp?: BuiltInMcpSessionConfig.
     • Pass provider-neutral MCP runtime config into provider.createSession(...).

   • src/providers/claude/runtime/claudeSession.ts

     • Add mcpConfigArgs?: string[] or a typed provider injection result.
     • Append --mcp-config <json> to Claude argv.
     • Consider --strict-mcp-config only if we explicitly want to suppress user/project MCP servers. For orchestration, probably do not use strict by default because users may already rely on their own MCP servers.

   • src/providers/codex/runtime/codexSession.ts

     • Add generated --config overrides for the built-in MCP server.
     • Need a spike to confirm CLI override syntax for nested tables. If nested mcp_servers.agent_code_orchestration.command=... works, use that. If not, use temporary CODEX_HOME overlay with a generated config.toml copied/merged from the real config.

   • src/renderer/src/workspace/hook/actions/session.ts

     • Extend spawn(...) options with enabled MCP domains.
     • Persist enough session metadata only if we decide MCP enablement survives reload.

   • src/preload/api/session.ts and src/main/ipc/session.ts

     • Thread MCP spawn options through session:spawn.

   Proposed src/mcp/ structure

   src/mcp/
     shared/
       domains.ts
       protocol.ts
       results.ts
     runtime/
       builtInServerRegistry.ts
       injectionConfig.ts
       controlBridge.ts
       controlBridgeTypes.ts
       sessionMcpState.ts
     servers/
       orchestration/
         server.ts
         tools/
   

   Use servers/ under src/mcp/ so future domains land beside orchestration rather than underneath it.

   Control bridge design

   MCP stdio server process should not import renderer/workspace code. It should call back to Agent Code through a local control bridge owned by main.

   Minimum bridge shape:

   • Main starts a local loopback HTTP server or IPC-like endpoint during app boot.
   • For each MCP-enabled session, main mints a short-lived capability token and records:
     • parent sessionId
     • enabled domains
     • allowed child/session scope
     • created timestamp
   • The MCP server is launched with env:
     • AGENT_CODE_MCP_CONTROL_URL
     • AGENT_CODE_MCP_TOKEN
     • AGENT_CODE_MCP_PARENT_SESSION_ID
     • AGENT_CODE_MCP_DOMAIN
   • Every bridge request validates token + domain + parent session scope.

   HTTP loopback is likely the most practical first bridge because stdio is already owned by the provider/MCP protocol, and the server process is external to Electron renderer. Bind to 127.0.0.1, random port, bearer token, no remote interface.

   Main-to-renderer mutation path

   The control bridge cannot directly update workspace state because linked-agent placement and Dispatch metadata live in renderer actions today.

   Add a small request/response bridge from main to renderer:

   • Main receives MCP control request.
   • Main validates token/scope.
   • Main sends a request to the focused BrowserWindow with a unique request id.
   • Renderer handles the request through workspace actions and replies on a paired IPC channel.
   • Main returns the result to the MCP server.

   This keeps the existing invariants intact: renderer owns tabs, detached sessions, linked-agent placement, and runtime drafts.

   Groundwork acceptance path

   The #155 implementation should finish when this is possible, even with only a dummy/test domain:

   1. Registry declares a built-in MCP domain.
   2. User/session spawn can enable that domain for one agent.
   3. Provider receives generated MCP config for that session only.
   4. Built-in MCP stdio server can start and call ping through the bridge.
   5. Bridge rejects missing/invalid token and wrong-session requests.
   6. No global Claude/Codex user config is mutated.

   Open decisions for first PR

   • Persist MCP enablement across app restart? Recommendation: no for MVP. Make enablement explicit per run until behavior is proven.
   • Use --strict-mcp-config for Claude? Recommendation: no for MVP. Inject built-in servers alongside user config.
   • Support both providers in first implementation? Recommendation: build provider-neutral API, implement Claude first if Codex nested override syntax is not immediately reliable.
   • Add @modelcontextprotocol/sdk dependency? Recommendation: yes, unless bundle policy objects. Use official SDK for server protocol and tool registration.
2. Juliusolsson05

   closed this as completedin #158on May 16, 2026