English ← MyDocs

MCP 隧道参考

代理配置字段、Tunnels REST API、证书要求和 setup CLI。

Note

MCP 隧道是一项研究预览功能。申请访问权限 即可试用。

代理配置

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

字段描述默认值
listen_addr监听的地址和端口。必填
log_level日志详细程度：debug、info、warn 或 error。info
shutdown_timeout优雅关闭期间等待进行中请求的时间。30s
tunnel_domain分配给隧道的基础域名。设置后，路由查找会从传入的主机名中剥离此后缀，这样 routes 键可以是纯子域名（wiki）。为空时，routes 键必须是完整的精确主机名。本指南中使用的子域名键形式为必填
tls.cert_file服务器 TLS 证书的路径。必填
tls.key_file服务器 TLS 私钥的路径。必填
routes子域名（或完整主机名）到上游 URL 的扁平映射（map[string]string，非列表）。首先尝试精确匹配，然后对 tunnel_domain 进行前缀匹配。匹配仅针对主机名；请求路径和查询字符串原样转发到上游。上游值必须恰好是 scheme://host:port（端口是必需的；包含路径会在配置加载时被拒绝，报错 invalid upstream (must be scheme://host:port)）。必填
upstream.allowed_ips代理允许连接的 IPv4 CIDR 范围或单个地址。与 disable_ip_validation 互斥。RFC1918 私有范围
upstream.disable_ip_validation完全禁用上游 IP 验证。与 allowed_ips 互斥。false
upstream.tls.ca_file用于验证上游 TLS 的 CA 包。无
upstream.tls.include_system_cas同时信任系统 CA 包进行上游 TLS 验证。false

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

Tunnels API

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

Warning

所有 MCP 隧道端点都需要通过 Workload Identity Federation 获取的具有 org:manage_tunnels 范围的 bearer 令牌。不接受 Admin API 密钥。

每个请求的必需头：

头值
AuthorizationBearer <token>（WIF 交换的令牌）
anthropic-version2023-06-01
anthropic-betamcp-tunnels-2026-05-19

证书要求

Setup 程序自动生成合规证书。这些要求仅在您通过自己的 PKI 签发证书时适用。

CA 证书

通过 POST /v1/organizations/tunnels/{tunnel_id}/certificates 上传。一个隧道最多可同时容纳两个活跃 CA 证书，以实现零停机轮换。

  • PEM 编码，单个证书，最大 8 kB。
  • BasicConstraints 扩展存在，CA:TRUE，标记为关键。
  • 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 或更强的签名。

Setup 程序生成一个有效期五年的 ECDSA P-256 CA 和一个具有通配符 SAN 和 90 天有效期的 RSA 4096 位服务器证书。

Setup CLI

setup 二进制文件包含在 mcp-proxy 镜像中。使用 docker compose run --rm setup <subcommand>（Compose）或依赖 chart 的 hooks 和 CronJobs（Helm）运行。

setup init

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

标志描述默认值
--api-urlClaude API 基础 URL。也可从 API_URL 读取。必填
--tunnel-id要附加的隧道 ID（tnl_...）。也可从 TUNNEL_ID 读取。必填
--output输出目标：dir:/path 或 k8s-secret:NAME。k8s-secret:mcp-tunnel（在 Kubernetes Pod 中运行时自动检测；否则必填）
--cert-duration服务器证书有效期。2160h（90 天）
--token-version变更检测字符串。新值会触发重新运行时的令牌轮换。无

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

setup renew-cert

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

标志描述默认值
--output输出目标：dir:/path 或 k8s-secret:NAME。k8s-secret:mcp-tunnel（在 Kubernetes Pod 中运行时自动检测；否则必填）
--cert-duration新证书有效期。2160h（90 天）
--renew-before如果现有证书剩余有效期超过此时间，则跳过续期。0（始终续期）

设置 --renew-before=720h 可使命令在剩余有效期超过 30 天时跳过续期，因此可以安全地按固定计划运行。