feat: add MCP server support for Electric Agents

[balegas]

Summary

• Adds new @electric-ax/agents-mcp package that bridges the official MCP TypeScript SDK into the existing AgentTool interface
• Supports stdio and Streamable HTTP transports with OAuth 2.1 + PKCE auth flow
• Connection pooling with lazy connect and idle timeout
• Tool namespacing (mcp__server__tool) following Claude Code conventions
• MCP resources exposed as agent tools (mcp__list_resources, mcp__read_resource)
• Conversational config management via Horton tools (mcp__manage__add_server, etc.)
• Config stored in .electric-agents/mcp.json with ${VAR} env var expansion
• OAuth tokens persisted in .electric-agents/mcp-auth.json (gitignored, mode 0600)
• Per-entity-instance overrides via spawn args
• Server instructions injected into agent system prompt
• Output size limiting (default 25K chars) with truncation
• 44 tests across 8 test files

Architecture

New package @electric-ax/agents-mcp plugs into agents-runtime via the existing AgentTool interface. The runtime stays MCP-agnostic; MCP is opt-in. The agents package wires MCP into Horton at bootstrap time.

McpClientPool → McpClient → @modelcontextprotocol/sdk
     ↓                ↓
 bridgeMcpTools    OAuthClientProvider
     ↓                ↓
 AgentTool[]      TokenStore (.electric-agents/mcp-auth.json)

Design docs

• Spec: docs/superpowers/specs/2026-04-24-mcp-server-support-design.md
• Plan: docs/superpowers/plans/2026-04-24-mcp-server-support.md

Test plan

• Unit tests for env var expansion (9 tests)
• Unit tests for config store (6 tests)
• Unit tests for token store (6 tests)
• Unit tests for tool bridge with namespacing + truncation (5 tests)
• Unit tests for resource bridge (3 tests)
• Unit tests for connection pool with mocked client (7 tests)
• Unit tests for config management tools (4 tests)
• Integration test for full flow with mocked MCP client (4 tests)
• Manual test with a real MCP server (e.g., @modelcontextprotocol/server-github)
• Manual test with OAuth flow against a remote MCP server

🤖 Generated with Claude Code

[balegas]

Code Review Follow-up Items

The following issues were identified during the final code review. Items 1-3 are deferred to a follow-up PR; items 4-7 are minor and can be addressed as needed.

Should address (follow-up PR)

1. Exponential backoff reconnection
The pool's acquire() has no retry logic — a single connection failure marks the server as failed and throws. The spec calls for 5 attempts with 1s base delay and 2x growth.

• File: packages/agents-mcp/src/pool.ts (connect method)
• Risk: Transient network issues or slow-starting stdio processes will prevent server use until the next handler invocation.

2. stdio process crash detection
No onclose handler is registered on the SDK Client or transport. If a stdio child process crashes, the pool entry stays in connected state and subsequent tool calls fail silently instead of triggering reconnection.

• File: packages/agents-mcp/src/client.ts
• Fix: Register client.onclose to emit a status change that the pool can react to.

3. Truncation uses per-block limit instead of running budget
truncateOutput() checks total chars across blocks but applies maxChars independently per block. Multiple blocks each just under the limit won't trigger truncation even if the total exceeds it.

• File: packages/agents-mcp/src/bridge/tool-bridge.ts
• Fix: Implement truncation as a running char budget across blocks.

Minor / acceptable for v1

4. getTools() connects eagerly on every handler wake
Every Horton wake calls mcp.getTools() which iterates all servers and calls acquire(). Consider caching discovered tools and only refreshing on listChanged notifications.

5. No config validation on load
ConfigStore.load() casts JSON.parse output directly. Malformed config files produce confusing runtime errors. Basic structural validation would help.

6. OAuth redirect port mismatch when callbackPort: 0
The redirectUrl getter returns a hardcoded port (9876) before the callback server starts, but the actual listening port may differ. This could cause issues with strict redirect URI validation during DCR.

7. console.log in OAuth provider fallback
Uses console.log instead of the project's pino logger when no onAuthUrl callback is provided.