MCP 隧道参考

代理配置

代理从 /etc/mcp-gateway/config.yaml（Compose）或渲染后的 ConfigMap（Helm，由 gateway.config.* 填充）读取其配置。

对于 https:// 上游路由，请至少设置 upstream.tls.ca_file 或 upstream.tls.include_system_cas 中的一项；否则代理没有用于验证上游证书的信任锚。

路由匹配

routes 是一个扁平的字符串映射（map[string]string），而不是列表。代理首先通过精确匹配查找传入的主机名，然后剥离 tunnel_domain 后缀并匹配剩余的子域名。匹配仅考虑主机名；请求路径和查询字符串会原封不动地转发到上游 MCP 服务器。

每个上游值必须严格为 scheme://host:port 格式。端口是必需的。如果包含路径，配置加载时会被拒绝并报错 invalid upstream (must be scheme://host:port)。

隧道 API

请参阅 MCP 隧道管理 API 参考，了解所有端点、请求和响应架构以及各语言的示例。

每个请求所需的标头：

证书要求

设置组件会自动生成符合要求的证书。以下要求仅适用于您通过自己的 PKI 签发证书的情况。

CA 证书

通过 POST /v1/organizations/tunnels/{tunnel_id}/certificates 上传。一个隧道最多可同时持有两个有效的 CA 证书，从而实现零停机轮换。

• PEM 编码，单个证书，最大 8 kB。
• 存在 BasicConstraints 扩展，其中 CA:TRUE，并标记为关键（critical）。
• 存在 SubjectKeyIdentifier 扩展。
• KeyUsage 包含 keyCertSign。
• 处于有效期内。
• RSA 2048 位或更大，或 ECDSA P-256 或更大，签名算法为 SHA-256 或更强。

服务器证书

由代理在内层 TLS 期间出示。

• 由已注册的 CA 直接签名（无中间证书）。
• 存在 AuthorityKeyIdentifier 扩展，且与 CA 的 SubjectKeyIdentifier 匹配。
• 主题备用名称（Subject Alternative Name）包含与 <route>.<tunnel-domain> 匹配的 DNS 名称。通配符 *.<tunnel-domain> 可覆盖所有路由。
• 如果存在 ExtendedKeyUsage 扩展，则其中包含 serverAuth。
• 处于有效期内。
• RSA 2048 位或更大，或 ECDSA P-256 或更大，签名算法为 SHA-256 或更强。

设置组件会生成一个有效期为五年的 ECDSA P-256 CA，以及一个带有通配符 SAN、有效期为 90 天的 RSA 4096 位服务器证书。

设置组件

设置组件以 setup 二进制文件的形式包含在 mcp-proxy 镜像中。使用 docker compose run --rm setup <subcommand>（Compose）运行它，或依赖 chart 的钩子和 CronJob（Helm）。

setup init

附加到您在 Console 中创建的隧道，生成 CA 和服务器证书，注册 CA，获取隧道令牌，并将所有输出写入目标位置。

该命令通过 Workload Identity Federation 进行身份验证。它读取 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_WORKSPACE_ID（可选），以及 ANTHROPIC_IDENTITY_TOKEN_FILE 或 ANTHROPIC_IDENTITY_TOKEN 中的恰好一个。有关这些变量的当前语义，请参阅 WIF 参考；设置组件从联合规则派生服务账户，因此不需要单独提供 ANTHROPIC_SERVICE_ACCOUNT_ID。

setup renew-cert

签发由存储的 CA 签名的新服务器证书。不进行任何 API 调用。

设置 --renew-before=720h 会使该命令在剩余有效期超过 30 天时成为空操作（no-op），因此可以安全地按固定计划运行。