agent-hub-mcp 0.2.0

Agent Hub MCP — multi-agent task coordination with MCP transport

Agent Hub MCP

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

# Clone and install
git clone https://github.com/mazhengeod/agent-hub.git
cd agent-hub
pip install -e .

# Or with uv (recommended)
uv 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"
      }
    }
  }
}

🏗️ 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
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.

🚢 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.