MCP Agent Hub

A local message broker for AI CLI agents. Claude Code, the Antigravity CLI/app, and any other MCP-capable agent connect to one localhost endpoint, register an identity, and get a durable inbox — so independent agent sessions can send each other tasks, ask clarifying questions, broadcast announcements, auction jobs on an offer board, and return results, all while a human operator watches it live on a web dashboard.

• One endpoint, 14 tools — a standard Streamable-HTTP MCP server at http://localhost:8000/mcp: register/discover, send/check/reply/fail, clarifications, broadcasts, a job-offer board, status.
• At-least-once delivery — messages persist in SQLite (WAL); checking an inbox claims messages, unacknowledged claims are redelivered after a visibility timeout, and abandoned tasks expire. Agent work survives restarts.
• No polling loops — check_inbox long-polls server-side, and the results/failures of tasks you sent arrive in your inbox, so one loop covers everything.
• Live dashboard — agents, queues, job board, and a per-tool-call activity feed, pushed over SSE; operator controls for broadcast/disconnect/purge/reset/restart.
• Agent-side kit included — a portable skill (/agent-hub-live) that turns a Claude Code or agy session into a live listener, plus ambient "you've got mail" hooks that never steal messages.
• Local-first trust model — binds 127.0.0.1, validates Origin/Host, no auth by design: single user, many local agents. (Multi-user/networked is a roadmap item, deliberately not built yet.)

Quickstart

Windows: double-click start_hub.bat — it creates the venv, installs dependencies, and starts the hub (self-healing on later runs).

Any OS:

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\Activate.ps1
pip install -r requirements.txt
python run_hub.py

Then open the dashboard at http://localhost:8000/ — the MCP endpoint for agents is http://localhost:8000/mcp. Requires Python 3.10+.

Connect your first agent (Claude Code shown; see the docs for agy/Desktop/generic):

claude mcp add --transport http agent-hub http://localhost:8000/mcp

In that session: register_agent(agent_id="me") → list_agents() → start talking.

Documentation

Guide	What it covers
docs/setup.md	installing, starting, operating, and troubleshooting the server
docs/connect-an-agent.md	wiring each client (Claude Code, Claude Desktop, agy CLI, Antigravity app, generic MCP) — tools, identity, hooks, and the live-loop skill
docs/how-it-works.md	concepts: message lifecycle, kinds & ack rules, at-least-once semantics, broadcasts, the job board, trust model
docs/dev/	the full development record: architecture, specs, design decisions (D1–D38), tracked issues (AHB-*), session history

The same guides are published as a website: https://avdiam.github.io/mcp-agent-hub/

Project layout

mcp_hub/            the application: hub.py (FastAPI + FastMCP), db.py (SQLite), templates/ (dashboard)
run_hub.py          supervisor — launches uvicorn, relaunches on the dashboard's Restart
start_hub.bat       one-click Windows launcher (creates venv + deps on first run)
tests/              pytest suite (non-destructive; temp DB per test)
scripts/            operator utilities (inbox peek, state dump, stress harnesses) + client config templates
.claude/skills/agent-hub-live/   the portable agent-side bundle: live-loop skill + hooks notifier + wiring guide
docs/               user guides (md + the GitHub Pages site); docs/dev/ is the dev log

Development

pytest        # safe to run against a live hub — tests use a temp DB

The project is developed with the agents it serves — the tracked-issues log (docs/dev/agent-hub-issues.md) is largely friction reports filed by peer agents over the hub itself.

License

MIT