已知限制与排障提示

  • 管理平台持久化 backend、工具组配置以及写入审批和审计记录；当前仍没有指标、持久化 MCP 目录、跨实例共享订阅或高可用协调，每个进程维护自己的后端连接、目录和 token view。
  • 当前版本不提供 stdio 后端接入、独立旧式 GET SSE 端点、原生 TLS、动态租户、opaque token introspection、Tasks、MCP Apps 或自定义 MCP 扩展。本地 connect 命令提供到 HTTP 网关的 stdio 连接；TLS 和外部限流由反向代理负责。
  • 个人凭证当前覆盖远程 MCP endpoint；HTTP 工具组、动态云/数据库凭证及供应商专用 SaaS OAuth 适配不在本版范围内。
  • 聚合器只声明并实现 tools、prompts、resources（含订阅）和 completions 能力；后端声明的其他能力不会自动变成网关能力。非法名称、非法 URI 模板和 SDK 拒绝的元数据会被省略。
  • 后端断线时保留 last-known-good 目录，但调用需要实时连接；required 后端会使 /readyz 变为 503，optional 后端不会阻塞整体就绪。
  • server.refresh_interval 是最大刷新周期，后端返回更短 TTL 时会更快刷新；不会提供强制即时刷新 API。
  • SIGHUP 不会重新读取 Docker 编排层的 --env-file；占位符使用的是当前进程环境，secret 或不可热改字段变化应重启进程。

常见现象对应关系：

  1. validate 报 environment variable ... is not set：按所选示例的变量清单注入实际服务进程，见基础示例或远程部署；required: false 不会跳过该后端的变量校验。
  2. /readyz 返回 503：查看 JSON 中 auth_verifier_ready 和 required_ready，再检查 OIDC discovery/JWKS 与 required 后端 URL。
  3. MCP 返回 401 且 challenge 带 resource_metadata：检查 Bearer 是否存在、签名/issuer/audience 是否正确。
  4. MCP 返回 403 insufficient_scope：按 challenge 中的 scope 补齐该后端的全部 required_scopes。
  5. 访问 /mcp 404：检查请求路径是否与 public_url 的路径完全一致；public_url 不能只写域名根路径。

配置相关常见误用：

现象 检查与处理
修改 YAML 后服务列表未变 托管数据库初始化后，改用控制台/API 编辑；不要删除数据库。
配了变量但 SSO/Vault 仍使用 ${...} 这些字段不展开；填实际字面值，Secret 用 *_env 变量名。
只有管理页，没有用户授权门户 另行启用 client_authorization 并注册普通用户客户端。
发布后仍看不到/不能执行工具 同时检查原始工具名、effect、Token/Grant Scope 和用户策略；validate 不验证工具实际存在。
SQLite 看似变成空库 核对 YAML 的位置及解析后的 database_path，不要意外连接到新路径。

能力与边界

  • 通过 MCP Streamable HTTP 连接多个后端；后端目录按分页读取，tools、prompts、resources 和资源模板列表会并行发现，并按后端通知或刷新周期更新。
  • 聚合 tools、prompts、resources、资源模板和 completion；转发 tool/prompt/resource 调用、资源订阅/取消订阅、进度通知和资源更新通知。
  • 后端 SSE 响应保持 streaming passthrough；检查 progress notification 时每个 event 最多缓存 1 MiB，超大 event 原样转发但跳过 progress 检查。
  • 针对官方 Go MCP SDK v1.7.0 客户端的 notifications/cancelled 消息缺少 2026-07-28 metadata，Hub 入站和后端出站都会做兼容规范化，使取消或取消订阅后的同一逻辑 MCP session 仍可复用；这是互操作性 shim，不是自定义扩展。
  • 以 backend.id 为命名空间，改写资源 URI，避免不同后端的同名能力和 URI 冲突。
  • 使用 OIDC discovery 和 JWKS 验证 Bearer JWT；按后端 required_scopes 过滤目录和调用。
  • 提供独立的 mcpbridge 程序，支持内建账号、LDAP 或 OIDC 浏览器登录、Agent 设备授权，以及本地 stdio 到 HTTP 的连接器，并自动刷新凭证。
  • 工具须显式发布，并受业务资源参数规则约束；写工具和未分类工具需要独立审批，支持多人复核、OIDC 加强认证、配置审批与签名审计投递。
  • 在 MCPHub 管理 SSO 用户、部门和用户组权限，通过个人授权门户与本地 Broker 控制客户端 Scope；setup 输出不含凭证的 MCP 配置，doctor 不执行工具即可检查访问问题。
  • 对原始后端 tool name 应用后端本地 tool_rules 和 Go path.Match；匹配规则的 scope 会合并去重，按 all-of 授权，并从 tools/list 隐藏未授权 tool。
  • 支持后端静态请求头，或 OAuth 2.0 client_credentials；两者不能同时提供 Authorization。
  • 管理 UI 按总览、服务接入、访问控制、治理与审计组织页面，支持持久化中英文选择、按角色显示入口和窄屏布局。工具组可以把手工 HTTP tool 和多个 OpenAPI 3.0/3.1 import 通过 /mcp 发布；组内共享 Base URL、Header、OAuth、scope 和 timeout，且不会暴露 raw HTTP proxy。
  • 支持内建账号或可选 LDAP/OIDC 登录的远程浏览器/CLI 管理，以及单实例网关的加密 SQLite 或 PostgreSQL 配置存储。
  • 可在 UI/API 中配置 endpoint 每秒请求数、突发容量和最大并发；默认不限流，调用者共享额度。
  • 提供健康、就绪和 RFC 9728 Protected Resource Metadata 端点；配置支持 SIGHUP 热重载。

后端连接失败时，MCPHub 会重试并保留已知的后端目录；目录可能仍可列出，但具体调用会在连接恢复前失败。启动时不会因为 required 后端暂时不可用而退出，/readyz 会保持 503；SIGHUP 创建新运行时则要求 candidate 中的 required 后端首次连接成功。后端产生的 JSON-RPC error 原样返回。网络或 transport 失败对外只返回 backend <id> unavailable，不会泄露内部 backend URL、query 或 credential。后端重连时，所有 tracked resource subscription 必须全部恢复成功后才会标记 ready；任一恢复失败都会保持 unavailable 并触发后续重连。