# MCP 隧道参考

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

---

<Note>
  MCP 隧道是一项研究预览功能。[申请访问权限](https://claude.com/form/claude-managed-agents) 即可试用。
</Note>

## 代理配置

代理从 `/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 参考](/docs/en/api/admin/mcp_tunnels)。

<Warning>
  所有 MCP 隧道端点都需要通过 [Workload Identity Federation](/docs/en/manage-claude/workload-identity-federation) 获取的具有 `org:manage_tunnels` 范围的 bearer 令牌。不接受 Admin API 密钥。
</Warning>

每个请求的必需头：

| 头 | 值 |
|---|---|
| `Authorization` | `Bearer <token>`（WIF 交换的令牌） |
| `anthropic-version` | `2023-06-01` |
| `anthropic-beta` | `mcp-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-url` | Claude 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](/docs/en/manage-claude/workload-identity-federation) 进行身份验证。它读取 `ANTHROPIC_FEDERATION_RULE_ID`、`ANTHROPIC_ORGANIZATION_ID`、`ANTHROPIC_WORKSPACE_ID`（可选），以及 `ANTHROPIC_IDENTITY_TOKEN_FILE` 或 `ANTHROPIC_IDENTITY_TOKEN` 之一。有关这些变量的当前语义，请参阅 [WIF 参考](/docs/en/manage-claude/wif-reference)；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 天时跳过续期，因此可以安全地按固定计划运行。