注意
“MCP tunnels”（MCP 隧道）目前处于“research preview”（研究预览）阶段。申请访问权限即可试用。
代理配置
代理从 /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 的键必须是精确的完整主机名。 |
当 routes 的键为裸子域名时必填 |
tls.cert_file |
服务器 TLS 证书的路径。 | 必填 |
tls.key_file |
服务器 TLS 私钥的路径。 | 必填 |
routes |
子域名或完整主机名到上游 URL 的映射。请参阅路由匹配。 | 必填 |
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 |
对上游 TLS 同时信任系统 CA 证书包。 | false |
对于 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)。
Tunnels API
Tunnels REST API 位于 /v1/tunnels，支持创建、列出和归档隧道，注册 CA 证书，以及显示或轮换隧道令牌。请参阅 Tunnels API 参考了解所有端点、请求和响应模式以及示例。
注意
之前位于
/v1/organizations/tunnels的 Admin API 接口（beta 标头mcp-tunnels-2026-05-19，作用域org:manage_tunnels）在迁移窗口期内 继续可用，并仍在 Admin API 参考中 附带弃用通知进行记录。要进行迁移，请将路径更新为/v1/tunnels，将 beta 标头更新为mcp-tunnels-2026-06-22，并将您的 WIF 令牌作用域更新为workspace:manage_tunnels。
警告
所有 MCP 隧道端点都需要通过 Workload Identity Federation（工作负载身份联合）获取的、具有
workspace:manage_tunnels作用域的 bearer 令牌。不接受 Admin API 密钥。
每个请求必需的标头：
| 标头 | 值 |
|---|---|
Authorization |
Bearer <token>（经 WIF 交换得到的令牌） |
anthropic-version |
2023-06-01 |
anthropic-beta |
mcp-tunnels-2026-06-22 |
证书要求
设置组件会自动生成符合要求的证书。以下要求仅适用于您通过自己的 PKI 签发证书的情况。
CA 证书
使用 POST /v1/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 或更强的签名。
设置组件会生成一个有效期为 5 年的 ECDSA P-256 CA，以及一个带有通配符 SAN、有效期为 90 天的 RSA 4096 位服务器证书。
设置组件
设置组件以 setup 二进制文件的形式随 mcp-proxy 镜像一同提供。使用 docker compose run --rm setup <subcommand>（Compose）运行它，或依赖 chart 的钩子和 CronJob（Helm）。
setup init
附加到现有隧道（或在未提供隧道 ID 时创建一个），然后生成 CA 和服务器证书，注册 CA，获取隧道令牌，并将所有输出写入目标位置。
| 标志 | 描述 | 默认值 |
|---|---|---|
--api-url |
Claude API 基础 URL。也可从 API_URL 读取。 |
必填 |
--tunnel-id |
要附加到的隧道 ID（tnl_...）。也可从 TUNNEL_ID 读取。省略时会创建新隧道；重新运行时会复用输出中已存储的隧道 ID。 |
无（创建隧道） |
--output |
输出目标：dir:/path 或 k8s-secret:NAME。Helm chart 传入 k8s-secret:<release>。 |
k8s-secret:mcp-tunnel（在 Kubernetes pod 中运行时自动检测；否则必填） |
--cert-duration |
服务器证书有效期。 | 2160h（90 天） |
--token-version |
变更检测字符串。新值会在重新运行时触发令牌轮换。Helm chart 和 Compose 示例均传入 1 作为初始值。 |
无 |
该命令通过 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 调用。
| 标志 | 描述 | 默认值 |
|---|---|---|
--output |
输出目标：dir:/path 或 k8s-secret:NAME。Helm chart 传入 k8s-secret:<release>。 |
k8s-secret:mcp-tunnel（在 Kubernetes pod 中运行时自动检测；否则必填） |
--cert-duration |
新证书有效期。 | 2160h（90 天） |
--renew-before |
如果现有证书的剩余有效期超过此时长，则跳过续期。 | 0（始终续期） |
设置 --renew-before=720h 会使该命令在剩余有效期超过 30 天时不执行任何操作，因此可以安全地按固定计划运行。