---
## `[ 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 