Skip to main content
Glama

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

指纹变了,旧进程被替换

只改 disabled_tools / hidden

不重启进程,只改可见集合

配置文件写坏了

保留旧配置继续服务,只记日志

验证与排查

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_error

check 会对每个服务器报 ✓ 名字: N 个工具 (...) 或 ✗ 名字: 原因,有失败时退出码为 1。

配置字段

字段

作用

对应 magpie

enabled

路由总开关

Library.MCPHub

idle_timeout

闲置多少秒关后端

hubIdle

on_demand_over

超过多少工具切按需

hubOnDemandOver

all_tools

强制全量工具

settings.RouterAllTools

api_key

外部调用令牌

gateway key

projects

项目作用域可见集合

projectHubs

服务器字段:name transport command args env cwd url headers hidden disabled_tools direct。

与 magpie 的对应

本实现

magpie

hub.HubPool

hubPool / backendOf

hub.Backend

backend

hub.Hub.named

hubNamed

hub.Hub.reload

hubPrune

transport.StdioConn

streamConn / dialStdio

transport.HTTPConn

httpConn / dialHTTP

transport.SSEConn

dialSSE

server.HubService

hubMCPCall

ondemand.*

hub_ondemand.go

config.ServerConfig.startup_fingerprint

hubKey

cli.cmd_add

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 并发 initialize

0.03s

并发度取决于后端本身。 mcphub 不限制并发,但如果后端(比如大多数 Python 写的 stdio MCP 服务器)是单线程处理请求,它的调用就会排队。实测同一个单线程后端上 4 个 0.8s 的调用要 3.2s——量的是后端,不是路由。

判断谁在排队:parallelism = Σ单个耗时 / 总墙钟。接近 N 说明真并行, 接近 1 说明后端在串行。

懒加载

阶段

行为

启动服务

不起任何后端进程

首次 tools/list 或 tools/call

才启动该后端(惰性)

工具列表

缓存到内存;命中时 0.3ms

闲置 idle_timeout(默认 600s)

关闭连接,但保留工具缓存

回收后再列工具

走缓存,不唤醒进程

回收后调用工具

自动重启,对调用方透明

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(跨平台优先)。

测试清单

文件

覆盖

数量

tests/run_checks.py

命名、消毒、截断、按需判定、权限、项目作用域

15

tests/e2e_stdio.py

真子进程:复用、调用、超时、错误

7

tests/e2e_http.py

HTTP 会话、404 重开、应答解析

5

tests/e2e_server.py

完整 MCP 会话与按需模式

13

tests/e2e_reload.py

热加载、管理接口、坏配置容错

8

tests/bench_concurrency.py

并发、懒加载、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 服务器自己会排队。

延迟

项

值

tools/call(本地服务器)

~170ms

tools/call(跨路由)

~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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Aggregates 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Aggregates 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.
      2
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Aggregates 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 npm
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Aggregates 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.
      -