Add MCP support to Electric Agents

[balegas]

Summary

Adds Model Context Protocol (MCP) support to Electric Agents so agents can call tools and read data from external MCP servers — both locally-spawned stdio servers and remote Streamable HTTP servers, with credentials managed by the runtime. Targets the Electron desktop app as the v1 host; the registry and bridges are embedder-agnostic for future deployed-runtime use.

For the architectural overview, see the spec at docs/superpowers/specs/2026-05-05-mcp-support-design.md. User-facing documentation lives under website/docs/agents/usage/mcp-servers.md and website/docs/agents/reference/mcp-{registry,server-config}.md.

How apps use MCP

Registry is the primary API. mcp.json and the desktop's settings.json mcp.servers block are file-based convenience layers that the runtime turns into the same Registry.applyConfig() calls.

Programmatic — Registry.addServer() / applyConfig()

BuiltinAgentsServer.mcpRegistry exposes the registry. Agent hosts add servers from code wherever it's the right shape — at boot from their own config source, in response to user actions, or per-session for tools an agent should only see during a specific task:

import { BuiltinAgentsServer } from "@electric-ax/agents"

const server = new BuiltinAgentsServer({
  agentServerUrl: "http://localhost:4437",
  port: 4448,
  workingDirectory: process.cwd(),
})

await server.start()

await server.mcpRegistry?.addServer({
  name: "stripe",
  transport: "http",
  url: "https://mcp.stripe.com/mcp",
  auth: {
    mode: "apiKey",
    headerName: "Authorization",
    key: process.env.STRIPE_MCP_KEY!,
  },
})

addServer returns a discriminated AddServerResult (ready / authenticating / error). applyConfig(cfg) is the bulk version — idempotent on unchanged entries, removes anything not in the supplied config; this is what file-based layers compile down to. subscribe(handler) exposes the live state stream, and reauthorize / disable / enable / removeServer cover single-server lifecycle.

File-based — mcp.json

For static, project-scoped configuration the runtime auto-loads <workingDirectory>/mcp.json on boot, watches it for changes, and hot-reloads adds, removes, and reconfigurations through applyConfig. mcp.json carries structural shape only — no secrets:

{
  "servers": {
    "honeycomb": {
      "transport": "http",
      "url": "https://mcp.honeycomb.io/mcp",
      "auth": { "mode": "authorizationCode", "scopes": ["mcp:read"] }
    },
    "git-local": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "${workspaceRoot}"]
    }
  }
}

For authorizationCode servers loaded from mcp.json, the runtime auto-wires keychainPersistence so OAuth tokens survive process restarts via the OS keychain.

Desktop settings layer

The Electron desktop adds a global mcp.servers block in its settings.json, applied to every workspace and shaped exactly like mcp.json (keyed by server name) so entries copy-paste between the two files. It composes with the workspace mcp.json instead of replacing it: non-conflicting servers from both files load together; on a name collision, the workspace mcp.json wins. Programmatic embedders (other than the desktop) pass the resolved array via BuiltinAgentsServer({ extraMcpServers }) — that's the in-memory shape settings.json is rewritten into when the desktop loads it.

Per-agent allowlist

Entity definitions opt into MCP servers explicitly via mcp.tools() from @electric-ax/agents-runtime:

ctx.useAgent({
  systemPrompt: "...",
  tools: [
    ...ctx.electricTools,
    ...mcp.tools(["sentry", "github"]), // explicit list
    // or: ...mcp.tools("*")              // every registered server
  ],
})

Tools are exposed to the model with always-prefixed names: mcp__<server>__<tool>. Built-in horton and worker opt in to all registered servers via mcp.tools("*").

Test plan

• pnpm --filter @electric-ax/agents-mcp test — 82 tests (subscribe + reauthorize coverage, stdio + HTTP e2e against @modelcontextprotocol/server-everything).
• pnpm --filter @electric-ax/agents test — 58 tests (covers the extraMcpServers + workspace-mcp.json merge in bootstrap-mcp.test.ts).
• pnpm --filter @electric-ax/agents-mcp typecheck; same for agents, agents-desktop, agents-server-ui.
• Smoke the desktop app: pnpm --filter @electric-ax/agents-desktop dev, configure an mcp.json (or settings.json mcp.servers) with an authorizationCode server, click Authorize → BrowserWindow opens → sign in → page flips to ready. Verify Disable + Enable round-trips without losing tokens.
• Verify the Settings → MCP Servers entry is hidden in the web build (no electronAPI).
• Confirm mcp.json hot-reload: edit the file, server is added/removed/reconfigured without a restart; in-flight tool calls finish on the old config.

Notes for reviewers

• Spec is the source of truth, not the early commit messages. docs/superpowers/specs/2026-05-05-mcp-support-design.md reflects the shipped architecture (desktop-IPC + operator-owned persistence). An earlier HTTP-mounted runtime + public CredentialStore was prototyped on this branch and removed; that history lives in git but isn't load-bearing for review.
• Public surface is in @electric-ax/agents-mcp — registry interface, transports, persistence helpers, bridges. @electric-ax/agents re-exports the types embedders need (McpRegistry, RegistrySnapshot, McpServerConfig, etc.).
• mcp.json resolution is relative to workingDirectory, not process.cwd(). This matters for the desktop, where the chosen workspace folder is the natural place to look. Headless embedders that don't pass a workingDirectory fall back to process.cwd().
• macOS keychain known limitation: keychainPersistence shells out to /usr/bin/security add-generic-password -w <value>, which puts the secret in argv (visible briefly via ps). Same posture as Claude Code's keychain integration. Documented inline in packages/agents-mcp/src/persistence/keychain.ts. The hardening path is a Rust sidecar over stdin using the keyring crate; not in scope here.
• Settings.json plaintext. API keys and the new mcp.servers block are stored unencrypted in <userData>/settings.json (mode 0644). Same posture as Claude Code's Linux fallback. Worth flagging if you want to push this through safeStorage.encryptString later — out of scope for this PR.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for electric-next ready!

Name	Link
🔨 Latest commit	4f996e5
🔍 Latest deploy log	https://app.netlify.com/projects/electric-next/deploys/69fe07e42471f300084a8b64
😎 Deploy Preview	https://deploy-preview-4289--electric-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[samwillis]

Reviewed with GPT-5.5 in an interactive session with me.

Overall, I’m happy with the architecture and design split here. The main tradeoff looks right to me: agent definitions declare the MCP capabilities they want, while the runner owns the concrete MCP server connections, config, auth, and environment-specific implementation. That keeps agent definitions portable across runners and lets different embedders provide different MCP implementations.

I also like that agents-mcp is a fairly distinct package. Keeping the core agents-runtime free of a direct dependency on MCP/SDK transport code feels like the right boundary, especially given browser/UI bundling concerns. The sentinel/tool-provider approach seems like a reasonable composition point.

A few things I think we should tighten before merging, or at least track clearly:

1. mcp.json should be explicit opt-in for BuiltinAgentsServer.

   Right now the built-in runner automatically looks for <workingDirectory>/mcp.json and applies it if present. Since stdio MCP servers can spawn local commands, I think project-scoped mcp.json loading should require an explicit flag or explicit path from the embedder/runner. I’m happy with supporting project config, but I don’t think simply selecting/running in a working directory should automatically execute MCP server config from that directory.

2. BuiltinAgentsServer.stop() should tear down MCP resources.

   The server creates an MCP registry, starts MCP transports, starts a config watcher, and registers the process-global mcp tool provider. On stop, it currently aborts wakes/closes HTTP/nulls refs, but I don’t think it closes MCP transports, disposes the watcher, or unregisters the tool provider. This could leak stdio child processes/watchers and leave stale provider state across desktop runtime restarts.

3. /api/runtimes appears to drop earlier entity types for a runtime.

   RuntimeRegistry.register() replaces by runtime name, while entity-type registration calls it once per type with types: [normalized.name]. Since the built-in runtime registers horton and worker separately under the same runtime name, the last registration can overwrite the earlier type. We should merge/accumulate types for a runtime or register the full type set in one go.

4. MCP config application errors should be surfaced/caught more reliably.

   In BuiltinAgentsServer, applyMerged fire-and-forgets mcpRegistry.applyConfig(...) inside a .then, so failures from applyConfig won’t be caught by the surrounding catch. That can produce unhandled rejections and leave the UI/embedder without a useful structured error state.

5. Missing requested MCP servers are currently silent.

   If an agent declares mcp.tools(['github']) but the runner has no ready github server, the sentinel expands to no tools and the agent runs under-equipped. I don’t think we need a full “required MCP dependency” model right now, but a warning for named unavailable servers would make this much easier to debug.

6. Minor follow-ups:

   • hashConfig() should probably include timeoutMs, otherwise timeout-only edits may not reconnect/reconfigure.
   • I’m not completely sold on mcp.tools('*') as the public syntax for “all MCP tools”; mcp.tools() or another default might read better. Not blocking.
   • Longer term, it would be nice to expose a helper for custom runners so embedders don’t have to copy the for (const entry of mcpRegistry.list()) ... bridgeMcpTool(...) loop.

None of the above changes my view that the main architecture is sound. I’m positive on the package split and on the decision for the runner, not the agent definition, to own MCP server connections/config/auth.

[balegas]

Thanks for the thorough review @samwillis. All six points addressed in c71b96a:

1. mcp.json is now explicit opt-in. New loadProjectMcpConfig?: boolean | string option on BuiltinAgentsServer, defaulting to off. The Electron desktop and the electric-ax CLI opt in (their use cases assume project scope); library embedders that construct BuiltinAgentsServer directly get the safer default. true reads <workingDirectory>/mcp.json; a string reads that exact path.

2. stop() tears down MCP resources. Added Registry.close() (closes every transport in parallel, forgets auth state, emits one final empty snapshot). BuiltinAgentsServer.stop() now also disposes the chokidar watcher (the closer was previously dropped on the floor by .catch(...)) and unregisters the mcp tool provider. Order is watcher → tool provider → registry → bootstrap → HTTP, so nothing fires against torn-down state during shutdown.

3. RuntimeRegistry.register() accumulates types. Producer-side stays as-is — entity-type POSTs run with concurrency, and any ordering-dependent fix would still race. The registry now merges types for an existing runtime (deduped, first-seen order) while letting the latest publicUrl win so a port-changed restart still updates correctly. The previous test that documented "replaces on re-registration" has been flipped.

4. applyMerged failures are now caught. Refactored to async/await so mcpRegistry.applyConfig rejections actually reach the catch (they were previously voided inside a .then callback, escaping as unhandled-rejection warnings while looking handled). Also exposed an opt-in onConfigError?: (error: unknown) => void callback for embedders to surface failures programmatically — the desktop can hook this if/when we want banner UI.

5. Missing requested MCP servers now warn. composeToolsWithProviders emits a single runtimeLog.warn per call listing any non-'*' allowlist names that aren't currently available (unknown or not yet ready). Wildcard sentinels stay silent; missing names dedupe within a call. Per-wake warning, self-correcting once config is fixed or servers come online.

6.

• a. hashConfig() now includes timeoutMs so timeout-only edits force a reconfigure instead of leaving entry.config.timeoutMs stale (the bridges read it per-call).
• b. mcp.tools() (no arg) is the canonical "every registered server" form. mcp.tools('*') kept as a back-compat alias. Built-ins horton/worker and the docs use the no-arg form.
• c. Helper for custom runners — deferred to a follow-up.

Test deltas:

• agents-mcp: +2 (Registry.close() happy path & error swallow, timeoutMs reconfigure, mcp.tools() default)
• agents-runtime: +5 (missing-server warnings)
• agents: +3 (bootstrap-mcp.test.ts — default-off ignores mcp.json, full start/stop/start round-trip, explicit-path opt-in)
• agents-server: +3 (runtime-registry merge, dedupe, port-change cases)