MCPHub
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcphub — 把 N 个 MCP 服务器路由成一个
magpie 的 MCP router
(internal/gateway/hub_mcp.go + internal/library/mcp_hub.go)的 Python 抽离实现。
零第三方依赖即可跑(stdio 传输)。
为什么做这个:magpie 用 Go 写成桌面应用,路由逻辑和 GUI、账户系统绑在一起。 把 MCP 路由单独抽出来,可以在任何地方跑、按需改造,也是一个能读的实现参考。
它做什么
agent ──> /mcp/hub/{agent} ──> MCPHub ──> github (stdio 子进程)
├──> sentry (Streamable HTTP)
└──> legacy (SSE)tools/list把各服务器的工具拍平成<server>__<tool>一个列表;tools/call按名字解回(server, tool)转发;每个服务器只起一份进程,所有 agent 共用;
工具多时切到按需模式,只给
find_tools和call_tool。
Related MCP server: gateway
快速开始
# 1. 起一个空配置
echo '{"servers": []}' > config.json
# 2. 加服务器(会校验名字与字段,写错不落盘)
python -m mcphub -c config.json add stdio github -- npx -y @modelcontextprotocol/server-github
# 3. 连一次确认能用
python -m mcphub -c config.json check
# 4. 起服务
python -m mcphub -c config.json --port 8765 -v在 Cursor / VS Code / Claude Desktop 里加:
{
"mcpServers": {
"mcphub": { "type": "http", "url": "http://127.0.0.1:8765/mcp/hub/cursor" }
}
}/mcp/hub(不带 agent)给任何第三方 app 用,看到全部服务器;
/mcp/hub/{agent} 只给该 agent 的服务器集合。
怎么加新的 MCP 服务器
有四条路,日常用第一条。
1. 命令行(推荐)
# stdio:本机命令,-- 之后全部是命令与参数
python -m mcphub -c config.json add stdio github -- npx -y @modelcontextprotocol/server-github
# 带环境变量
python -m mcphub -c config.json add stdio playwright -- npx -y @playwright/mcp@latest \
--env BROWSER=chromium
# Streamable HTTP
python -m mcphub -c config.json add http sentry \
--url https://mcp.sentry.dev/mcp \
--header "Authorization=Bearer YOUR_TOKEN"
# 旧版 SSE
python -m mcphub -c config.json add sse legacy --url http://127.0.0.1:9000/sse
# 其他可选项
# --disabled-tool NAME 关掉某个工具(可重复)
# --hidden 不参与路由,先存着
# --direct 点名直连,不走路由
# --cwd /path 命令的工作目录add 会先做校验,错了直接不写:名字非法、stdio 缺 command、
http 缺 url、transport 不认识。
2. 直接改配置文件
格式见 config.example.json。关键点:servers 是数组,每项 name 唯一,
name 会进工具名,只能用字母数字和 _ -。
3. 环境变量引用,别写明文密钥
env 与 headers 里的 ${VAR} 会在启动时换成环境变量的值:
{ "name": "github", "transport": "stdio", "command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } }没设置的变量保持原样,便于发现配错。
4. 加完怎么生效
不用重启服务。两条路:
自动:后台每 2 秒看配置文件的 mtime 与大小,变了就重载;
手动:
python -m mcphub reload或POST /admin/reload。
重载时按启动指纹判断:
变化 | 行为 |
新增服务器 | 下次列工具时惰性启动,首次使用才起进程 |
删掉服务器 | 立刻结束它的后端进程 |
改了命令/参数/url/env | 指纹变了,旧进程被替换 |
只改 | 不重启进程,只改可见集合 |
配置文件写坏了 | 保留旧配置继续服务,只记日志 |
验证与排查
python -m mcphub -c config.json ls # 列服务器与状态
python -m mcphub -c config.json check # 真连一次,报每个服务器有几个工具
curl http://127.0.0.1:8765/admin/servers # JSON 形式,含 last_errorcheck 会对每个服务器报 ✓ 名字: N 个工具 (...) 或
✗ 名字: 原因,有失败时退出码为 1。
配置字段
字段 | 作用 | 对应 magpie |
| 路由总开关 |
|
| 闲置多少秒关后端 |
|
| 超过多少工具切按需 |
|
| 强制全量工具 |
|
| 外部调用令牌 | gateway key |
| 项目作用域可见集合 |
|
服务器字段:name transport command args env cwd url headers
hidden disabled_tools direct。
与 magpie 的对应
本实现 | magpie |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Library 的 Add 表单 |
把另一个 MCP 路由接进来(bridge)
magpie 自己的 hub(/mcp/.../hub)本身就是一个路由。把它当普通 HTTP 服务器接进来
会得到 magpie__notion__notion-search 这种双前缀,所以要标 bridge:
{"name": "magpie", "transport": "http",
"url": "http://127.0.0.1:3425/mcp/magpie/hub", "bridge": true}url 里含 /hub 时会自动识别成 bridge,不写也行。
bridge 的行为:
它的工具保留原名(
notion__notion-search),不再拼一层前缀;find_tools的server参数两种名字都认:magpie(本地服务器名)与notion(对方路由里的服务器名);请求它时带
X-Magpie-Router,对方据此剔除自己的 bridge,两个路由互相接也不会成环;反过来,我们自己收到带
X-Magpie-Router的请求,也不列出自己的 bridge。
并发与懒加载
并发
场景 | 实测 |
纯路由层(ping) | 579 req/s,48 并发下 p50 40ms |
1 个后端,8 个并发调用(每个 1s) | 1.01s(串行需 8s,8× 加速) |
5 个后端各 1 个并发调用(每个 1s) | 1.01s(串行需 5s,5×) |
5 个后端同时冷启动 | 0.15s |
12 并发 | 0.03s |
并发度取决于后端本身。 mcphub 不限制并发,但如果后端(比如大多数 Python 写的 stdio MCP 服务器)是单线程处理请求,它的调用就会排队。实测同一个单线程后端上 4 个 0.8s 的调用要 3.2s——量的是后端,不是路由。
判断谁在排队:parallelism = Σ单个耗时 / 总墙钟。接近 N 说明真并行,
接近 1 说明后端在串行。
懒加载
阶段 | 行为 |
启动服务 | 不起任何后端进程 |
首次 | 才启动该后端(惰性) |
工具列表 | 缓存到内存;命中时 0.3ms |
闲置 | 关闭连接,但保留工具缓存 |
回收后再列工具 | 走缓存,不唤醒进程 |
回收后调用工具 | 自动重启,对调用方透明 |
N 个请求同时首连 | singleflight,只起 1 个进程 |
工具表还有一层缓存(TTL 2s)+ singleflight:tools/call 不需要每次都把
所有后端的工具重列一遍。这一层把单次调用从 3.6s 降到 170ms。
检索是向量召回吗
不是。工具召回是词法打分(ondemand.score):
查询词出现在 hub 名里 → 3 分;
出现在描述里 → 1 分;
整串出现在名字里 → 再加 5 分。
magpie 的 MCP 路由全程没有 embedding。它的向量检索在另一个子系统
(internal/memembed,记忆检索,用 sentence-transformers 的 ONNX 模型),
与工具路由无关。
测试
python tests/run_checks.py # 路由算法:命名、消毒、按需判定(15 项)
python tests/e2e_stdio.py # 真子进程:进程复用、调用、超时(7 项)
python tests/e2e_http.py # HTTP:会话、404 重开(5 项,需 httpx2)
python tests/e2e_server.py # 完整 MCP 会话(13 项)
python tests/e2e_reload.py # 热加载、管理接口、坏配置容错(8 项)e2e_http.py 与 transport.HTTPConn 用 httpx2(MCP SDK 2.x 同款)。只用
stdio 的话不需要它。
已知偏差
没有 magpie 的
HubVisitor全部规则:网页伪装判定、root 转发、Magpie Browser 的 per-key 会话都未实现。没有插件服务器(本进程内调用,不走 URL)。
没有跨机同步与 mTLS。
direct语义简化:不参与路由,需要调用方自己配直连条目。重载按 2 秒轮询 mtime,不是 inotify(跨平台优先)。
测试清单
文件 | 覆盖 | 数量 |
| 命名、消毒、截断、按需判定、权限、项目作用域 | 15 |
| 真子进程:复用、调用、超时、错误 | 7 |
| HTTP 会话、404 重开、应答解析 | 5 |
| 完整 MCP 会话与按需模式 | 13 |
| 热加载、管理接口、坏配置容错 | 8 |
| 并发、懒加载、singleflight | 13 |
共 61 项,全部通过。
最简跑法(不需要 pytest):
python tests/run_checks.py
python tests/e2e_stdio.py
python tests/e2e_server.py实测数据
召回
场景 | 结果 |
102 个工具,单次召回 | 67μs |
复杂度 | 严格 O(N),每工具 0.7–0.87μs |
检索方式 | 全量线性扫描,无倒排索引、无向量 |
tests/show_scoring.py 与 tests/show_no_index.py 可复现这些数字。
并发
场景 | 结果 |
纯路由层(ping) | 579 req/s,48 并发 p50 40ms |
1 后端 8 并发调用(每个 1s) | 1.01s(串行 8s,8× 加速) |
12 并发 initialize | 0.03s |
并发度最终取决于后端:单线程的 MCP 服务器自己会排队。
延迟
项 | 值 |
| ~170ms |
| ~1.2s |
工具表缓存命中 | 0.4ms |
已知问题
桥接(
bridge)的服务器与本地服务器同名时,工具会变成x__tool和x__tool_2两份。去重正确,但语义重复,建议本地不要与上游重复配置同一个服务器。
致谢
路由的设计(命名空间、进程池、按需发现、防递归桥接)来自 magpie,本仓库是它的 Python 重述。 Magpie 与 mcphub 均为 MIT 许可。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP federation gateway: route, govern and observe agent tools across clouds and MCP servers.
The MCP server that finds MCP servers. Aggregates Official Registry, Glama, and Smithery.
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
Toolstile is a managed MCP gateway that connects remote MCP servers behind one endpoint, with per-agent permissions, shared accounts and activity logs. Connect at https://mcp.toolstile.com/mcp over Streamable HTTP with OAuth; sign in at https://toolstile.com, select a workspace and connect your upstream servers. Available tools, resources and prompts depend on that workspace and the agent's granted access.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAggregates multiple MCP servers behind a single endpoint, letting MCP clients access all their tools through one URL and token while namespacing tools to avoid collisions.MIT
- AlicenseNot gradedqualityBmaintenanceAggregates multiple MCP servers behind a single endpoint so that clients can reach every one of their tools through one connection instead of configuring each server separately. It simplifies setup and keeps tool access in one place when many servers are in play.2MIT
- AlicenseNot gradedqualityAmaintenanceAggregates multiple backend MCP servers (Stdio, SSE, and Streamable HTTP) into a single unified endpoint, exposing their combined tools and resources via SSE, Streamable HTTP, or Stdio. It also offers an optional web admin UI for managing server connections, tool enablement, and live configuration reloads.120 npmMIT
- FlicenseNot gradedqualityAmaintenanceAggregates multiple backend MCP servers (Stdio, SSE, and Streamable HTTP) and exposes their combined tools and resources through a single unified SSE or Streamable HTTP endpoint, or as a standalone Stdio server. It routes tool calls and resource requests to the right backend and offers optional web-based admin, authentication, and per-tool control.-