Host user-authored MCP servers as Agent Code extensions

[Juliusolsson05]

Status (quality-loop audit, 2026-09-25)

Landed: #1144 added user MCP servers: config paste, per-provider and per-agent toggles, and launch-time injection.

Remaining: Hosted servers: manifest discovery, app-owned lifecycle with status and logs, servers packaged in extensions, scaffolding.

Acceptance: This is a feature; tracked as type:feature, outside the quality loop's fix scope.

Original report

Use case

Agent Code should be able to act as a local platform for user-authored MCP servers.

Today, built-in MCP domains live inside Agent Code internals. That is fine for first-party capabilities like orchestration, AI Workspace, agent transcripts, and future root access. But users who want to add their own MCP server should not need to modify core app files or understand Agent Code's internal MCP host implementation.

If someone is already using Agent Code, the app can be the natural place to discover, host, toggle, and attach local MCP servers to Claude/Codex agents.

Desired model

Keep two concepts separate:

• Built-in MCP domains: first-party Agent Code capabilities such as orchestration, ai_workspace, agent_transcripts, and future root_access.
• Extension MCP servers: user/plugin authored MCP servers that Agent Code discovers and hosts without requiring edits to core source files.

Extension MCP servers should use a code structure close to the standard MCP SDK so authors do not have to learn a custom Agent Code abstraction before writing useful tools.

Example possible layout:

extensions/
  my-mcp-server/
    agent-code.mcp.json
    package.json
    src/server.ts

Example manifest shape:

{
  "id": "my-server",
  "title": "My Server",
  "description": "Adds project-specific tools.",
  "entry": "src/server.ts",
  "transport": "stdio",
  "defaultEnabled": false
}

Exact paths/schema are open for design. The important constraint is: adding an MCP server should not require editing src/mcp/runtime/createBuiltInMcpServer.ts or any other core registry file.

Platform responsibilities

Agent Code should provide the platform layer:

• discover extension MCP server manifests from documented locations
• validate manifest shape and ids
• start/stop hosted MCP server processes
• expose status: disabled, running, failed, needs install, needs auth, etc.
• surface logs/errors per server
• make servers toggleable per agent/session, similar to built-in MCP domains
• inject selected extension server configs into Claude/Codex session startup/reload
• show which agents have which extension MCP servers attached
• avoid attaching all extension servers to all agents by default

Authoring goals

MCP server authors should be able to write normal MCP code with the official MCP SDK shape.

Agent Code should wrap hosting/discovery/configuration, not force every server into a bespoke internal API.

Future nice-to-have:

• command to scaffold a new extension MCP server
• template with TypeScript + MCP SDK
• dev-mode reload for local server changes
• marketplace/plugin integration later

Safety and lifecycle requirements

Extension MCP servers are local code execution and must be treated as explicit opt-in capabilities.

Requirements:

• disabled by default unless explicitly enabled
• visible per-agent enablement status
• clear failure state if server startup fails
• server logs/debug output accessible from Agent Code diagnostics
• no silent global attachment to every agent
• no access to built-in privileged APIs unless explicitly granted through a documented capability boundary
• extension crashes should not crash Agent Code or block unrelated agents from starting

Acceptance criteria

• Add a documented extension MCP server discovery path and manifest format.
• Add a host/registry layer for extension MCP servers separate from built-in MCP domains.
• Add UI/command support to enable/disable an extension MCP server for a Claude/Codex agent.
• Spawn/reload injects enabled extension MCP server configs into the provider session.
• Built-in MCP domains remain first-party and separate from extension MCP servers.
• A minimal example extension server can be added without editing core app source.
• Errors/status/logs for extension servers are visible enough to debug startup and runtime failures.

[Juliusolsson05]

Kept open (owner decision, 2026-09-27): still relevant. Note from the triage: user MCP servers that are pasted in and injected at launch shipped in #1144. What's left is letting an extension contribute an MCP server, ideally reusing that same userMcp injection path.