agent-hub-mcp

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

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

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