Setting up the hub server

Get the hub running on your machine, then wire your agents to it with the Connect an Agent guide.

Prerequisites

Python 3.10+ on PATH
Windows, macOS, or Linux — the hub is pure Python (the one-click launcher is Windows-only)

Quick start (Windows)

Double-click start_hub.bat (or run it from any terminal). It is portable and self-healing: it finds the project from its own location, creates the virtual environment and installs dependencies on first run (or when the venv/ is missing or broken), then launches the supervisor and keeps the window open so errors stay visible. Ctrl+C stops it.

Manual start (any OS)

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

On Debian/Ubuntu, python -m venv may fail until you sudo apt install python3-venv first.

run_hub.py is a small supervisor: it launches uvicorn (mcp_hub.hub:app on 127.0.0.1:8000) and relaunches it when the process exits with code 42 — which is what the dashboard's Restart button triggers. Any other exit stops the supervisor.

What you get once it's running

Where	What
`http://localhost:8000/`	the operator dashboard (live, SSE-pushed)
`http://localhost:8000/mcp`	the MCP endpoint agents connect to (Streamable HTTP)
`hub.db` (project root)	the SQLite database — all state lives here
`logs/hub.log`	server log (each supervisor launch appends a header)

Sanity check: open the dashboard — an empty hub shows zero agents and an idle activity feed. The first register_agent from any client appears there within a second.

Operating it

Restart (pick up code changes): dashboard Restart button, or POST /api/restart. The DB is untouched; clients reconnect on their next call.
Soft reset (wipe state, keep running): dashboard Reset / POST /api/reset — clears agents and messages. Irreversible.
Purge old data: dashboard Purge / POST /api/purge — removes old terminal-state rows.
Stop: Ctrl+C in the supervisor window.

The /api/* endpoints validate Origin/Host headers — call them from the dashboard or from localhost tooling, not from foreign origins.

Tunables

All constants are single-sourced at the top of mcp_hub/db.py: STALE_THRESHOLD (90 s), VISIBILITY_TIMEOUT (600 s), MESSAGE_TTL (24 h), and the broadcast/offer caps. Edit + Restart to apply.

Tests

pytest

Tests are non-destructive — they run on a temporary database, so it's safe to run them while your live hub is serving agents.

Troubleshooting

Symptom	Fix
`start_hub.bat` loops on venv creation	Is Python installed and on PATH? The window shows the failing step.
Port 8000 already in use	Stop the other process, or edit the port in `run_hub.py` (and everywhere clients point).
Dashboard shows nothing after a code edit	You edited but didn't restart — use the Restart button.
Client can't reach `/mcp`	Hub not running, or the client isn't on the same machine — the hub is localhost-only by design (see the trust model).