Agent Switchboard

Agent Switchboard is a local MCP service that connects existing Codex and Claude Code desktop sessions, Fabric, and Maestro. Clients share a capability registry and session/project interface; each provider also exposes its native tools. The broker preserves the native session owner, permissions and spending controls.

The service runs on the Mac because the two desktop adapters require local IPC. Fabric and Maestro reach it through authenticated HTTPS, normally a Cloudflare Tunnel. The tunnel supplies ingress; Node and SQLite on the Mac own dispatch, receipts and event delivery. A sleeping or disconnected Mac is unavailable.

Status

The implementation and automated protocol tests cover durable operations, MCP Tasks, resource subscriptions, human elicitation relay and MCP Events webhooks. Live acceptance is in progress. A registered connection, a dispatch receipt and completed agent work are different claims. See the live matrix and implementation record. The protocol compatibility notes distinguish webhook receipt, resource invalidation, Tasks and native agent wakeup.

capabilities_get reports exact supported operations, normalized input schemas, read-only semantics, observed availability and provider versions. Unsupported operations remain explicit. This service does not manufacture desktop lifecycle support from unrelated host tools or substitute a separate CLI conversation.

Related MCP server: universal-peer-mcp

Install

Use macOS with Node.js 24 or later and node:sqlite:

npm ci
npm run check
npm test

Create a private directory such as ~/.local/state/agent-switchboard with mode 0700. Keep config.json and separate random bearer-token files for operator, codex, claude, fabric and maestro there, all mode 0600. Each token must have at least 32 characters; use 32 random bytes or more. Never commit them.

Configuration

Use absolute paths and configure each provider explicitly. The desktop entries select the local IPC adapters.

{
  "port": 8796,
  "stateDir": "/absolute/private/switchboard",
  "clients": {
    "operator": { "tokenFile": "/absolute/private/operator.token", "providers": ["codex", "claude", "fabric", "maestro"] },
    "codex": { "tokenFile": "/absolute/private/codex.token", "providers": ["codex", "claude", "fabric", "maestro"] },
    "claude": { "tokenFile": "/absolute/private/claude.token", "providers": ["codex", "claude", "fabric", "maestro"] },
    "fabric": { "tokenFile": "/absolute/private/fabric.token", "providers": ["codex", "claude", "fabric", "maestro"] },
    "maestro": { "tokenFile": "/absolute/private/maestro.token", "providers": ["codex", "claude", "fabric", "maestro"] }
  },
  "providers": {
    "codex": { "kind": "desktop" },
    "claude": { "kind": "desktop" },
    "fabric": {
      "url": "https://your-fabric.example/tutti",
      "tokenFile": "/absolute/private/fabric-native.token",
      "supportsInputRequired": true
    },
    "maestro": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/maestro-mcp/bin/maestro-mcp.mjs"],
      "env": { "MAESTRO_BROKER_SOCKET": "/absolute/private/maestro/broker.sock" },
      "supportsInputRequired": true
    }
  }
}

supportsInputRequired pins the native connection to MCP 2026-07-28 and enables form/URL elicitation relay. Set it only for a verified compatible provider. For Fabric, codexCredential: {file, serverName} can replace tokenFile; the adapter rereads the matching exact-endpoint OAuth credential on every request. The native credential grants access to Fabric. Client tokens above grant access to this broker; these are separate credentials.

Start node bin/hub.mjs, or install its LaunchAgent with node bin/install-service.mjs. Set SWITCHBOARD_CONFIG when using a nondefault configuration path. See operations for restart and tunnel behavior.

Register node /absolute/path/to/agent-switchboard/bin/client.mjs as a stdio MCP server in each desktop client. Set its SWITCHBOARD_TOKEN_FILE to that client's private token file. Set SWITCHBOARD_URL if you change the default local port. The shim connects to the shared local service; it does not start a second broker. Existing conversations may need an MCP reload or a new session to load updated registration.

For Fabric and Maestro use the tunnel's HTTPS /mcp endpoint and the respective client bearer token. Maestro's connector is agent_switchboard with credential service type agent_switchboard_mcp; store the URL in metadata.mcp_endpoint. Enable the integration in the exact intended session or project through native capability controls. Saving credentials alone does not enable an agent tool.

Use

Call agents_list, then capabilities_get for the target provider. A status request uses this shape:

{ "provider": "maestro", "action": "status", "input": { "id": "exact-native-session-id" } }

Use the read-only sessions_query tool for that request. Mutations add a stable input.requestId; reusing it with changed arguments is refused. Use provider_tools_list with an exact name before provider_call for functions outside the normalized interface. For mixed native tool families, consult the provider's action schema as well as its broad discovery schema.

A mutation returns an operation receipt or an MCP Task when the client supports Tasks. Inspect native status/transcripts to establish execution completion. Cancellation of a Task only cancels queued dispatch; stopping a running agent requires sessions with action stop and any native exact-turn guard.

Session event subscriptions

Use events_catalog to discover turn, error, output block, input request, state, and observation gap events. Use events_watch for a durable exact-session journal, MCP Events for signed webhooks, or events_follow for a bounded peer notification to another session. See event subscriptions for the catalog, race-free job subscription sequence, and provider limits.

Protocols and delivery

• Tasks: durable caller-scoped task handles, status, cancellation acknowledgment and input-response continuation. Unknown dispatch outcomes are retained across restart and never replayed automatically.

• Subscriptions: resource invalidation notifications and replayable local journal cursors. Resource notifications do not themselves start model turns.

• Elicitation: bounded native form/URL input requests, with responses supplied through the MCP client's human interaction path. No model answer argument is exposed as human authorization.

• Events: webhook subscription verification, signed delivery, durable cursors, expiry, bounded retries and key rotation. Webhook acknowledgment does not establish a client wakeup or model action. Host acceptance remains a separate live test, especially for local desktop clients.

All peer content stays untrusted. Native approval controls remain authoritative. The broker does not provide isolation between an authorized caller and the recipient agent's granted tools. Use distinct tokens and narrow provider grants.

Verification

npm test uses controlled services, temporary databases and sockets; it does not message running agents. npm run test:live exercises registered connections and read-only fixture checks, writing private reports under ignored evidence/live/. Mutation and actual originating-agent tests need exact dedicated fixtures and separate recorded evidence. See the matrix runbook.

The original seven-tool desktop-only stdio entrypoint remains at server.mjs. Its legacy guide and protocol notes describe that narrower interface.

MIT license.