mcp-switchboard

<div align="center">

<img src="assets/banner.svg" alt="mcp-switchboard — a message bus for AI agents" width="100%">

![protocol](https://img.shields.io/badge/protocol-MCP-6cd5e6?style=flat-square&labelColor=030d14)
![transport](https://img.shields.io/badge/transport-streamableHttp-6cd5e6?style=flat-square&labelColor=030d14)
![state](https://img.shields.io/badge/state-SQLite-6cd5e6?style=flat-square&labelColor=030d14)
![dependencies](https://img.shields.io/badge/dependencies-none-2ecc71?style=flat-square&labelColor=030d14)
![image](https://img.shields.io/badge/image-ghcr.io-6cd5e6?style=flat-square&labelColor=030d14&logo=docker&logoColor=6cd5e6)
![license](https://img.shields.io/badge/license-AGPL--3.0-6cd5e6?style=flat-square&labelColor=030d14)

</div>

---

## `[ the problem ]`

You're running multiple AI agents. Claude Code handles one task, an Ollama-backed daemon handles another. When they need to share information, *you* are the relay — copying output from one, pasting it into the other, manually keeping them in sync.

That's the human-as-middleman problem. Switchboard eliminates it.

## `[ what it is ]`

A centralized, self-hosted MCP server that acts as a message bus between agents. Any MCP-capable agent — Claude Code, Hermes, Ollama, or anything you add later — connects with one HTTP URL and a bearer token. From there, agents can:

- Send direct messages or broadcast to channels
- Long-poll for real-time message delivery (sub-second)
- Track each other's presence and activity
- Coordinate on tasks without human intervention

One container. One URL. No broker, no Redis, no external dependencies. State lives in SQLite and survives restarts.

## `[ why not a2a ]`

[Google's Agent-to-Agent protocol](https://developers.google.com/agent-to-agent) is the enterprise standard for agent coordination. It's well-designed and well-funded. It also requires implementing Agent Cards, capability discovery schemas, and a new protocol stack — which is the right call if you have an engineering team and an enterprise deployment.

> [!TIP]
> If you want two agents talking to each other *this afternoon*, Switchboard is the answer.

|  | **Switchboard** | **A2A** |
|---|---|---|
| **Setup** | `docker run`, one env var | Agent Cards + capability discovery + protocol implementation |
| **Dependencies** | None (SQLite) | Protocol stack |
| **Best for** | Homelab, small teams, self-hosted | Enterprise, multi-vendor, large scale |
| **Governance** | You | Linux Foundation (Google, Anthropic, OpenAI, Microsoft, AWS) |

## `[ quick start ]`

Self-host the whole thing on any Docker box. One command brings it up, generates a token, and prints the line your agents use to connect:

```bash
$ git clone https://github.com/jemplayer82/mcp-switchboard && cd mcp-switchboard
$ ./deploy/quickstart.sh          # Windows: .\deploy\quickstart.ps1
```

Prefer to drive Compose yourself:

```bash
$ docker compose up -d
$ docker compose logs switchboard   # shows the auto-generated token
```

Or a bare `docker run` — no config at all:

```bash
$ docker run -d --name switchboard \
    -p 3107:3107 -v switchboard-data:/data \
    ghcr.io/jemplayer82/mcp-switchboard:latest
$ docker logs switchboard            # the token is printed here
```

No token? One is generated on first boot, persisted to the `/data` volume, and printed in the logs. Pin your own anytime with `-e SWITCHBOARD_MCP_TOKEN=…` (or `.env`).

```bash
$ curl -sf http://localhost:3107/healthz
# → {"ok":true}
```

That's it. Point your agents at `http://your-host:3107/mcp` — or let the [one-command installer](#-wiring-an-agent--one-command-) do it.

> [!NOTE]
> Examples throughout use port **3107** — what the container listens on and the Compose default. To publish a different host port, set `SWITCHBOARD_PORT` (the container stays on 3107) and substitute it wherever you see `3107` below.

## `[ how it works ]`

```
  Claude Code  ──┐
                 ├──► http://your-host:3107/mcp  ──► bus.js (singleton)
  Hermes daemon ─┘         Bearer auth                  ├─ EventEmitter  (sub-second wakeups)
                                                        └─ SQLite        (durable, survives restarts)
```

- **Stateless transport, stateful bus.** Each HTTP request gets its own transport; all handlers close over one shared `bus` singleton. State is shared across all connections automatically.
- **Real-time via long-poll.** `wait_for_message` holds the HTTP response open (up to 25s) and returns the instant a message arrives. Loop it for live receipt.
- **Durable delivery.** Messages and per-agent read cursors live in SQLite. An agent that restarts picks up exactly where it left off — no messages lost, no duplicates.
- **Presence awareness.** Agents call `set_status` to report what they're working on. `get_activity` returns a cross-agent feed so any agent can see what the others are doing.
- **`POST /sync`.** A REST shortcut for hooks and scripts: publishes the agent's current activity AND drains its unread inbox in one round trip. Returns `{ok, messages, cursor}` plus the full activity feed when `include_activity:true`.

## `[ wiring an agent · one command ]`

The switchboard serves its own installer. Point a host at it and it writes the config, drops the hooks, merges your `settings.json`, adds the MCP entry, and drops the [Workflow-checkpoint convention](#-claude-code-workflows--mid-run-switchboard-checkpoints-) into `~/.claude/CLAUDE.md` (skip with `--skip-claude-md`) — the whole manual dance below, done for you. The base URL is baked into the script as it's served, so the agent targets the exact host it downloaded from — no IP to type.

**Prerequisites:** `node` on `PATH` (Claude Code already requires it); `curl` too on Linux/macOS. Nothing else.

```bash
# Linux / macOS
$ curl -fsSL http://your-host:3107/install.sh | sh -s -- --agent-id myagent --token <token>

# add --with-daemon to also install the headless responder (wakes on a message
# even when no session is open — see [ headless responder ])
```

```powershell
# Windows (PowerShell)
> $env:SWITCHBOARD_AGENT_ID='myagent'; $env:SWITCHBOARD_MCP_TOKEN='<token>'
> irm http://your-host:3107/install.ps1 | iex
```

`<token>` is the value from your server's startup logs (or whatever you pinned). Restart your Claude Code session afterward so the hooks load. Re-running is safe — every step is idempotent and backs up what it touches.

**Verify it worked.** After restarting, the agent should show up online. From any connected agent call `list_agents`, or check over REST:

```bash
$ curl -s -X POST http://your-host:3107/sync \
    -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
    -d '{"agent_id":"myagent","activity":"idle"}'
# → {"ok":true, "messages":[...], "cursor":N}   (a 200 means you're wired in)
```

**Uninstall.** Remove the four switchboard hook entries from `~/.claude/settings.json`, delete `~/.switchboard/config.json` and `~/.claude/hooks/switchboard-*.mjs`, and drop the `switchboard` entry from `mcpServers` in `~/.claude.json`. If you installed the daemon: `systemctl --user disable --now claude-code-agent`. The Workflow-checkpoint section in `~/.claude/CLAUDE.md` (marked with an HTML comment) is harmless to leave — delete it manually if you want it gone.

> [!TIP]
> **Already a Claude agent connected to the bus?** Just call the `bootstrap` tool with your `agent_id`. It returns the one-line command *plus* the full hook contents and merge instructions, so you can self-install without leaving the session.

> [!NOTE]
> The installer and hook code are served **unauthenticated** on purpose — they contain no secrets. The token is supplied by you at install time and is the only sensitive value. `curl … | sh` runs remote code, so pull the script and read it first if you want: `curl http://your-host:3107/install.sh`.

## `[ wiring your agents · manual ]`

What the installer does, if you'd rather do it by hand.

### Claude Code

Add to `~/.claude.json` under `mcpServers`:

```json
"switchboard": {
  "type": "http",
  "url": "http://your-host:3107/mcp",
  "headers": { "Authorization": "Bearer your-secret-token" }
}
```

Claude Code works as a **sender** anytime during a live session. As a **responder**, install the hooks (see `[ hooks ]` below) — they deliver inbound messages automatically during live sessions without you relaying anything.

### Hermes / Any HTTP-MCP Daemon

Same URL and bearer token in its MCP config.

To receive messages, call `wait_for_message` in a loop — it waits up to 25 seconds and returns the moment something arrives. When it returns (message or timeout), call it again immediately. That's it.

> [!IMPORTANT]
> Explicitly pass `timeout_seconds: 25` — the tool's default is **20s**, not the full 25s max. Don't poll with short intervals either way: a reply from another agent takes as long as a Claude tool call, which is almost always longer than a 1–5 second poll. Loop immediately with no sleep between calls.

### Any Other MCP Client

Same pattern: HTTP URL + `Authorization: Bearer` header. Any client that speaks MCP over streamable HTTP works.

## `[ provider compatibility ]`

Switchboard speaks standard streamable-HTTP MCP. How each major provider connects:

| Provider | Native MCP | Notes |
|---|---|---|
| **Claude Code** | ✓ | HTTP MCP + hooks (see above) |
| **OpenAI** (Responses API) | ✓ | Pass `"type":"mcp"` in the `tools` array per request — [docs](https://platform.openai.com/docs/guides/tools-remote-mcp) |
| **xAI Grok** | ✓ | Same shape as OpenAI Responses API — `authorization` field in the tool object |
| **Google Gemini** | ✓ experimental | `streamablehttp_client` in the Python SDK; `gemini mcp add` in the CLI |
| **Open WebUI** (+ Ollama) | ✓ (v0.6.31+) | Admin → External Tools → MCP (Streamable HTTP) → paste URL + token |
| **LangChain** | ✓ | `langchain-mcp-adapters` — `MultiServerMCPClient` with `streamable_http` transport |
| **LlamaIndex** | ✓ | `llama-index-tools-mcp` — `BasicMCPCli