Agent Hub MCP

English | 中文

Multi-agent task coordination server built on the Model Context Protocol

Agent Hub is a lightweight coordination layer for multi-agent workflows. It provides structured task dispatch, assignment tracking, inter-agent messaging, handoff documents, and human-in-the-loop approval — all accessible via the MCP protocol.

✨ Features

• 🔌 MCP Streamable HTTP — any MCP client connects directly
• 📋 Task → Round → Assignment state machine with operator approval gates
• 💬 Inter-agent messaging with deduplication and inbox pull
• 🤝 Structured handoff documents — agents pass work with context, not just messages
• 🔒 Distributed locks with TTL-based lease expiry
• 🛡️ Bearer token authentication — each agent authenticates independently
• 📦 Zero-dependency database — SQLite with WAL mode, no external DB needed
• ⚡ 5-minute setup — install, configure tokens, run

🚀 Quick Start

Install

# Install from PyPI (recommended)
pip install agent-hub-mcp

# Or install from source
git clone https://github.com/mazhengeod/agent-hub.git
cd agent-hub
pip install -e .

Configure Agent Tokens

Create ~/.config/agent-hub/agents.env:

# Format: AGENT_ID=BEARER_TOKEN
claude-code=your-secret-token-here
codex-desktop=another-secret-token

Optionally, create ~/.config/agent-hub/config.yaml for tuning:

max_rounds: 3
max_assignments_per_round: 6
max_messages_per_task: 40
lease_minutes: 90

Run

# Start the MCP server (defaults to 127.0.0.1:8765)
python -m agent_hub.server

# Or use the CLI
hubctl serve

Connect from Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "agent-hub": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token-here"
      }
    }
  }
}

After the MCP client connects, call agent_register once for each token-backed agent. The token in the request decides the agent_id; name and capabilities are descriptive metadata:

{
  "name": "Claude Code",
  "capabilities": "[\"planning\", \"code-review\", \"implementation\"]"
}

You only need to re-register when you want to update the displayed name or capabilities.

🏗️ Architecture

State Machine

Task (draft)
  │
  ├─► Round 1: awaiting_operator_approval
  │     ├─► Operator approves ─► dispatched
  │     │     ├─► Assignment: pending ─► claimed ─► in_progress ─► completed
  │     │     └─► All assignments done ─► awaiting_review
  │     └─► Operator rejects ─► back to awaiting_operator_approval
  │
  └─► Review verdict: approved ─► Task completed
      Review verdict: changes_requested ─► Round 2 (re-plan)

16 MCP Tools

Tool	Description
hub_status	Server version and transport info
agent_register	Register an agent with name and capabilities
agent_heartbeat	Ping to confirm agent is alive
inbox_pull	Pull unread messages for the calling agent
message_send	Send a message to another agent, or omit to_agent for broadcast
message_ack	Mark a message as read
task_draft_create	Create a new task in draft state
round_plan_submit	Submit a round plan with assignments
assignment_list	List assignments for the calling agent
assignment_claim	Claim a pending assignment
assignment_progress	Report progress on an assignment
assignment_complete	Complete an assignment with a handoff document
handoff_get	Retrieve a handoff document
review_submit	Submit a review verdict (approved/changes_requested)
lock_acquire	Acquire a distributed lock with TTL
lock_release	Release a held lock

Operator CLI

hubctl provides manual operator controls:

hubctl approve <round-id> [note]   # Approve a round for dispatch
hubctl reject  <round-id> [note]    # Reject a round (needs re-plan)
hubctl close   <task-id>            # Close a task
hubctl status  <round-id>           # Show round status
hubctl list-tasks                   # List all tasks
hubctl list-rounds [task-id]        # List rounds

🔐 Security

• Bearer token auth — each agent has its own token in agents.env
• Tokens are SHA-256 hashed in the database, never stored in plaintext
• Local-only by default — server binds to 127.0.0.1:8765
• No external dependencies — SQLite WAL mode, no Redis/Postgres needed

⚠️ Never commit agents.env or .mcp.json to version control. They contain authentication tokens. Tokens are plaintext in agents.env because the server must verify incoming Bearer tokens. The SQLite database stores only token hashes for audit metadata.

🚢 Production Deployment

systemd

A template service file is provided in systemd/agent-hub.service.template. Install with:

# Generate service file with your user and path
./scripts/install.sh

# Or manually:
sed -e "s|%USER%|$(whoami)|g" \
    -e "s|%WORKDIR%|$(pwd)|g" \
    -e "s|%VENV%|$(pwd)/.venv|g" \
    systemd/agent-hub.service.template > ~/.config/systemd/user/agent-hub.service

systemctl --user daemon-reload
systemctl --user enable --now agent-hub

Environment Variables

Variable	Default	Description
AGENT_HUB_HOST	127.0.0.1	Server bind address
AGENT_HUB_PORT	8765	Server bind port
AGENT_HUB_DB	~/.local/share/agent-hub/hub.db	SQLite database path

📂 Project Structure

agent-hub/
├── src/agent_hub/
│   ├── __init__.py       # Package init
│   ├── server.py          # FastMCP server with 16 tools
│   ├── service.py         # State machine logic & rules
│   ├── storage.py         # SQLite storage layer
│   ├── models.py          # Pydantic data models
│   ├── auth.py            # Bearer token verification
│   └── cli.py             # hubctl operator CLI
├── migrations/
│   └── 001_init.sql       # Database schema
├── tests/                 # Test suite
├── examples/              # Example configs
├── systemd/               # Service templates
├── docs/                  # Documentation
└── pyproject.toml         # Package config

🧪 Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run with auto-reload (if using uvicorn)
python -m agent_hub.server

📄 License

MIT — use it, fork it, ship it.

🙏 Acknowledgments

Built with FastMCP and the Model Context Protocol specification.