How do I use mcp-agent-hub?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-agent-hub I'm the master; assign coder-1 the login task and track progress." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-agent-hub

让多个 Agent 客户端（Claude Code、Cursor、MiMo、Aider 等，可 2 个以上）在本机或局域网互通协作的 MCP 服务。

协作模型：手动设主 + 其余全是子代理

手动指定一个主理人（master）：在某个客户端启动时 --role-type master，或调用 set_master
其余全部是子代理（subagent）：数量不限；入网时自动挂靠到当前主理人
支持本地（多个 stdio 进程共享一个 SQLite）和局域网（Streamable HTTP，多客户端接入同一 Hub）

                ┌─────────────────────┐
                │  主理人 master       │  ← 手动指定（--role-type master / set_master）
                │  拆解 · 派单 · 盯进度 │
                └──────────┬──────────┘
           dispatch_task   │   report / escalate
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
 ┌────────────┐     ┌────────────┐     ┌────────────┐
 │ 子代理 A    │     │ 子代理 B    │     │ 子代理 C    │  ← 可任意多个
 │ coder      │     │ reviewer   │     │ tester     │
 └────────────┘     └────────────┘     └────────────┘
        │                  │                  │
        └──────────────────┼──────────────────┘
                           ▼
              共享黑板 remember/recall
              任务看板 · 消息收件箱 (SQLite)

安装

依赖：Python 3.12+，推荐 uv。

git clone <repo-url> mcp-agent-hub
cd mcp-agent-hub
uv sync
# 或仅运行时
uv pip install -e .

快速开始（Linux 示例）

场景 1：本机多客户端（stdio + 共享 DB）

所有客户端指向同一个 AGENT_HUB_DB 即可互通。主理人手动设在其中一个客户端上。

export AGENT_HUB_DB=/tmp/agent-hub.db

# ① 手动设主：这一端是主理人
mcp-agent-hub stdio --name boss --role-type master --role orchestrator

# ② 其余全是子代理（可开任意多个）
mcp-agent-hub stdio --name coder-1    --role-type subagent --role implementer --capabilities code,test
mcp-agent-hub stdio --name reviewer-1 --role-type subagent --role reviewer    --capabilities review,docs
mcp-agent-hub stdio --name tester-1   --role-type subagent --role tester      --capabilities test

主理人客户端配置（examples/01-master.json）：

{
  "mcpServers": {
    "agent-hub": {
      "command": "mcp-agent-hub",
      "args": ["stdio", "--name", "boss", "--role-type", "master", "--role", "orchestrator"],
      "env": { "AGENT_HUB_DB": "/tmp/agent-hub.db" }
    }
  }
}

子代理客户端配置（换 --name / --role 即可再开 N 个，见 examples/02-04）：

{
  "mcpServers": {
    "agent-hub": {
      "command": "mcp-agent-hub",
      "args": ["stdio", "--name", "coder-1", "--role-type", "subagent", "--role", "implementer", "--capabilities", "code,test"],
      "env": { "AGENT_HUB_DB": "/tmp/agent-hub.db" }
    }
  }
}

场景 2：局域网 / 跨机器（Streamable HTTP）

一台机器起 Hub，其他机器的 Agent 客户端都连上来：

mcp-agent-hub serve --host 0.0.0.0 --port 8765 --db /var/lib/agent-hub/hub.db
# 或
./scripts/run-serve.sh 0.0.0.0 8765

客户端配置：

{
  "mcpServers": {
    "agent-hub": {
      "url": "http://192.168.1.10:8765/mcp"
    }
  }
}

HTTP 模式下多个客户端共享一个服务进程。各方先 join_hub 登记身份（主理人可 set_master），工具也可带 agent 参数指定身份。

手动设主的两种方式

启动时指定：mcp-agent-hub stdio --name boss --role-type master
运行时指定：任意 Agent 调用 set_master(name="boss")（exclusive=true 会把其他人降为子代理，并改挂汇报线）

之后 join_hub(role_type="subagent") 的新 Agent 会自动挂靠到当前主理人。

协作流程（1 主 + N 子）

步骤	主理人	子代理（×N）
1. 设主	`--role-type master` 或 `set_master`	`join_hub(role_type=subagent)` 自动挂靠
2. 派单	`dispatch_task(title, assignee=coder-1)`	收到 order 消息
3. 领会	—	`my_assignments` / `read_inbox`
4. 执行	`team_status` 看全员负载	`report_progress(task_id, 50, note)`
5. 同步	`broadcast` / `send_message`	`send_message` / `escalate`
6. 沉淀	`remember` / `recall`	`remember` / `recall`
7. 交付	收到 report	`complete_task(task_id, result)`

多个子代理可同时干活；任务池模式用 claim_task 抢占，避免重复劳动。

MCP 工具一览

分组	工具	说明
身份	`whoami` / `join_hub` / `list_agents` / `set_status`	登记与在场
设主	`set_master`	手动指定谁是主理人
主理人	`dispatch_task` / `team_status`	派单、盯全员负载
子代理	`my_assignments` / `claim_task` / `report_progress` / `complete_task` / `escalate`	领活、认领、汇报、交付、上报
任务	`create_task` / `list_tasks` / `update_task`	看板与改派（支持 `parent_id` 子任务树）
消息	`send_message` / `broadcast` / `read_inbox` / `mark_read`	点对点、全员广播、房间
房间	`create_room` / `join_room` / `list_rooms`	频道协作
黑板	`remember` / `recall` / `forget`	跨 Agent 共享记忆（带版本）
诊断	`hub_stats` / `activity_log`	总览与事件流

环境变量

变量	默认	说明
`AGENT_HUB_DB`	`./agent-hub.db`	SQLite 路径（多客户端务必同一文件）
`AGENT_NAME`	—	默认 Agent 名（也可用 `--name`）
`AGENT_ROLE_TYPE`	`subagent`	`master` 或 `subagent`（主理人请设为 `master`）
`AGENT_ROLE`	—	职责描述
`AGENT_CAPABILITIES`	—	能力标签，逗号分隔
`AGENT_REPORTED_TO`	—	子代理汇报的主理人名字（不填则自动挂靠）

开发

uv sync
uv run ruff check src tests
uv run ruff format src tests
uv run pyright src
uv run pytest
uv run python tests/e2e_mcp_handshake.py

设计说明

手动设主：--role-type master / set_master / join_hub(role_type=master) 三种入口。
自动挂靠：子代理入网时若未指定 reported_to，自动指向当前主理人。
派单：dispatch_task 建任务并给子代理发 order 消息；可派给任意多个子代理。
回报：report_progress / complete_task 自动给主理人发 report；escalate 标 blocked 并发 escalation。
抢占：claim_task 事务内抢占，失败会提示当前持有者。
存储：SQLite + WAL，多进程/多客户端并发安全。
传输：stdio（本机多客户端共享 DB）；serve（局域网 Streamable HTTP）。

License

MIT

mcp-agent-hub

mcp-agent-hub

协作模型：手动设主 + 其余全是子代理

安装

快速开始（Linux 示例）

场景 1：本机多客户端（stdio + 共享 DB）

场景 2：局域网 / 跨机器（Streamable HTTP）

手动设主的两种方式

协作流程（1 主 + N 子）

MCP 工具一览

环境变量

开发

设计说明

License

Maintenance

Resources

Related MCP Connectors