mcp-hub 是一个双时代 Model Context Protocol（MCP）网关，用于将多个 stdio MCP 服务器从单个容器统一对外提供，并通过 HTTPS 发布。它在每个端点上同时支持 MCP 2026-07-28 和 2025-11-25 两个修订版本，客户端可自行选择，且无法从响应中分辨所使用的是哪个版本。
用途 mcp-hub 主要解决无法在本地启动进程的 MCP 客户端（如 ChatGPT 连接器、Claude Web 与 Code、Mistral Le Chat、Cursor、LibreChat 以及其他 Streamable-HTTP 客户端）访问后端 MCP 服务器的问题。它用单个进程替代为每个 stdio MCP 服务器单独部署认证代理容器（每个都需要完整镜像、OAuth 栈、主机名和 compose 栈）的方案。
主要能力
- 路径路由：通过 https://host/paperless、https://host/homeassistant 等路径访问不同服务器。
- /hub 聚合端点：注册单个连接器即可通过 6 个元工具（list_servers、list_tools、get_tool_schema、call_tool、wake_server、sleep_server）访问所有服务器，避免用 N×工具模式淹没模型上下文。
- 按服务器工具过滤：通过 allowTools / denyTools 决定暴露哪些工具，支持精确名称或 list_* 前缀；被过滤的工具不会出现在 tools/list 中，即使客户端调用也会在服务器被唤醒前拒绝。
- 内置 OAuth 2.1：以单个密码保护登录，支持 CIMD（Client ID Metadata Document）优先的注册方式，同时保留 RFC 7591 动态注册；也支持通过管理 CLI 手动签发凭据。
- API 令牌：为无法进行 OAuth 的客户端（OpenAI Responses API、xAI API、Gemini API）提供长期有效的资源绑定令牌。
- 上游 OAuth：远程服务器若使用 OAuth，可配置 oauth 块，由 hub 自行注册、获取并刷新令牌。
- 按需生命周期：stdio 和 docker 服务器在使用时启动，空闲 60 分钟后休眠，期间从持久快照应答 initialize / tools/list；keepAlive: true 可豁免单个服务器，IDLE_TIMEOUT_MINUTES=0 可豁免整个 hub。
- 监督与热重载：子进程被 ping 并在死亡时以指数退避重启；mcp.json 的编辑只会启动/停止/重启受影响的服务器。
- 无状态 Streamable HTTP：无会话状态，避免 claude.ai 不发送 DELETE 的重连行为导致进程或内存泄漏。
- 双时代支持：每个端点（/hub、/<name>/mcp 和 --stdio）同时应答两个 MCP 修订版本；2026 修订版包含 elicitation（子服务器的问题可传递到最终用户）和 subscriptions（hub 向客户端提供 subscriptions/listen，并按子服务器所理解的版本订阅）。
- 变更通知：客户端可打开 subscriptions/listen 流，获知子服务器的工具、提示或资源变更；hub 以子服务器理解的方式订阅（2026 服务器用 subscriptions/listen，2025 服务器用 resources/subscribe）。
- 轻量设计：单个 Node 进程，无数据库（状态为一个 JSON 文件加 /data 下的签名密钥），十个运行时依赖，提供多架构镜像，目标是在树莓派等单板计算机上舒适运行。
使用方式 配置位于 /config/mcp.json，格式与 Claude Code 的 mcpServers 完全一致，可 1:1 复制条目；${VAR} 从容器环境展开。stdio 服务器（command / args / env）作为受监督的子进程启动；远程服务器（type: "http" 或 "sse"，带 url 和可选 headers）作为 MCP 客户端连接，并在每个请求注入配置的 headers。
部署方式：
- 选项 A（推荐）：使用 GHCR 预构建镜像，支持 linux/amd64 和 linux/arm64，标签包括 latest、X.Y.Z、X.Y 和 sha-<commit>。
- 选项 B：从源码构建。
- 选项 C：通过 npm 安装（包名 @ni-c/mcp-hub，提供 mcp-hub 和 mcp-hub-admin 二进制文件）；容器仍是推荐部署方式。
连接客户端：将 https://<host>/hub（或 https://<host>/<name>/mcp）添加为自定义连接器，使用密码登录一次。Claude Code 可使用 claude mcp add -t http name https://<host>/<name>/mcp。仅 API 客户端使用管理 CLI 签发的令牌。
管理 CLI 可列出或撤销客户端，也可为无法进行 OAuth 的客户端签发长期、资源绑定的 API 令牌。
适用场景
- 需要从无法本地启动进程的 MCP 客户端访问多个 stdio MCP 服务器。
- 希望用单个连接器替代为每个服务器单独注册。
- 需要在资源受限设备（如树莓派）上运行 MCP 网关。
- 需要为不同信任级别的服务器提供隔离（type: "docker" 通过 Docker API 跨容器边界通信，或 type: "unix" / "tcp" 连接套接字）。
限制与注意事项
- 所有 stdio 子进程共享 hub 的 Unix 用户，可读取其挂载文件；只应安装完全可信的 stdio 服务器。不同信任级别的服务器应放入独立容器。
- 未设置非空 PASSWORD 或 bcrypt PASSWORD_HASH 时，HTTP hub 仍会启动，但登录被禁用，无法批准客户端或签发令牌。
- /data 保存 Ed25519 JWT 密钥、已注册 OAuth 客户端、批准和刷新令牌；应挂载为卷，重建会使所有连接器授权失效。
- 每个访问令牌绑定到一个资源；RESOURCE_BOUND_TOKENS=false 为迁移模式，会签发可访问所有路径的未绑定令牌。
- TRUSTED_PROXIES 决定 req.ip 和登录速率限制的计数方式；未设置时按 IP 限制退化为单一全局计数器。
- 反向代理需满足 TLS 终止、允许 WebSockets/SSE、关闭代理缓冲、请求超时高于 310 秒、请求体限制不高于 MCP_BODY_LIMIT，并传递 X-Forwarded-Proto / Host。
- 保留名称包括 mcp、hub、authorize、token、register、login、consent、health、livez、revoke、jwks、interaction、session、userinfo、upstream、.well-known。
- 变更通知在 2026-07-28 上通过 subscriptions/listen 承载，其状态是打开的响应而非会话表。
- 关于 2025-11-25 客户端的具体行为，资料在结尾处被截断，暂未提供完整说明。
