backends

YAML-only 模式至少配置一个后端；管理模式允许从空数据库启动并在网页注册第一个后端。每个 id 必须匹配 [A-Za-z0-9_-]{1,32}，并按大小写不敏感规则保持唯一；允许大写字母。

字段 默认值 说明
id 无 tool/prompt 名称使用的对外命名空间和配置 ID；不能包含点号。名称保留大写，而 resource/template URI authority 使用小写 ID。
url 无 必填绝对 URL。默认只接受 HTTPS；仅当 allow_insecure_http: true 且主机是 localhost、IPv4/IPv6 loopback 时才允许 HTTP。
required false required 后端影响 /readyz。运行中断线会使就绪变为 503；连接循环会继续重试。
require_client_grant false 对此 endpoint 强制客户端授权，需要启用用户门户。个人 Vault 账号必须显式设为 true。
credentials 无 Vault shared / personal 凭证来源；需要全局 vault，与此 backend 的服务 oauth 和冲突的静态认证头互斥。见 Vault 专题。
required_scopes [] 该后端所需的 JWT scope，按 all-of 判断；scope 不能含空白，也不能重复。
published_tools [] 获准发布的原始工具名，精确匹配并区分大小写，不支持通配符；留空不发布任何工具。
tool_rules [] 可选的后端本地 tool 策略。每条规则包含 match glob，以及 effect、approval、required_scopes、resource_rules 中至少一项。effect: read 可直接执行；write 或未分类需要审批。匹配基于原始后端 tool name，使用 Go path.Match，整串且区分大小写。
request_timeout 继承 server.request_timeout 该后端连接、目录发现、刷新和调用的超时；必须大于 0。
rate_limit {} Endpoint 共享速率、突发容量和并发限制；默认不限流。
allow_insecure_http false 仅为 loopback 本地 HTTP 开关；不会放宽 server.public_url 或任何 issuer 的 HTTPS 要求。
headers {} 每次后端 MCP HTTP 请求附加的静态头。值支持环境变量展开，不能含 CR/LF；名称大小写不敏感且不能重复。Accept、Content-Type、任意 Mcp-* 头，以及 Host、Content-Length、Connection、Proxy-Authorization、Proxy-Authenticate 等均由 HTTP/MCP transport 管理并被拒绝。
oauth 无 后端 OAuth 配置；目前唯一允许的 type 是 client_credentials。与静态 Authorization 头互斥。

oauth 字段如下：

字段 说明
type 必须为 client_credentials。
issuer 必填绝对 HTTPS OAuth issuer；metadata 的 issuer 必须与它精确一致。
client_id / client_secret 必填，建议只通过 ${...} 环境变量提供。
scopes 发给后端 OAuth token endpoint 的 scope 列表；它与 required_scopes（验证进入 MCPHub 的 JWT）是两套独立的 scope。

后端 OAuth discovery 和 token 请求不会带上该后端的静态 headers；数据面请求才会附加 headers 并自动复用/刷新 client-credentials token。Discovery 只从 RFC 8414/OIDC metadata 读取并精确校验 issuer 和 token_endpoint，不要求交互式 authorization 或 PKCE metadata。OAuth metadata 响应上限为 1 MiB。后端和 OIDC HTTP 客户端都不跟随重定向。

可选的服务账号 OAuth 片段，不属于基础模板：只有接入此类服务时才将以下条目放入 backends，并为这条目设置全部 4 个变量；required: false 只影响连接失败的处理。工具仍需审核后显式发布。

- id: crm
  url: ${MCPHUB_CRM_BACKEND_URL}
  required: false
  required_scopes: [mcp:crm.read]
  published_tools: []
  oauth:
    type: client_credentials
    issuer: ${MCPHUB_CRM_OAUTH_ISSUER}
    client_id: ${MCPHUB_CRM_CLIENT_ID}
    client_secret: ${MCPHUB_CRM_CLIENT_SECRET}
    scopes: [crm.read]