使用 Helm 部署 MCP 隧道

使用 Anthropic Helm chart 在 Kubernetes 集群上安装 MCP 隧道技术栈。

Anthropic Helm chart 将 MCP 隧道技术栈安装为单个 Deployment，并将其附加到您在 控制台 中创建的隧道。

准备工作

您需要：

• **在控制台中创建的隧道。**请按照 创建隧道 的步骤操作，并记录隧道 ID（tnl_...）。
• 一种让 chart 向 Tunnels API 进行身份验证的方式。
  • **编程访问（推荐）。**Chart 的 setup Job 通过 Workload Identity Federation 进行身份验证，获取隧道令牌，生成 CA，向 Anthropic 注册，并将所有内容存储在 Secret 中。您需要一条范围为 org:manage_tunnels 的联邦规则。
  • **手动方式。**跳过编程访问。您将 从控制台获取隧道令牌，自行生成 CA 和服务器证书，在控制台中注册 CA，并将凭据作为 Secrets 提供给集群。
• 可以使用 helm 和 kubectl 部署的 Kubernetes 集群。Without programmatic access 选项卡还需要 openssl（1.1.1 或更新版本）。
• **从集群到 api.anthropic.com（443 TCP）和隧道边缘（7844 TCP 和 UDP）的出站网络连接。**参见完整的 网络要求。
• 一个或多个 MCP 服务器正在运行，并且可以从集群上通过您将在 gateway.config.routes 下配置的地址访问。如果您还没有，使用下方的示例服务器。

可选：使用示例 MCP 服务器

如果您没有可用于测试的 MCP 服务器，请使用这个最小示例：

kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel apply -f - <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-mcp-src
data:
  hello_server.py: |
    from mcp.server.fastmcp import FastMCP

    mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)


    @mcp.tool()
    def hello(name: str = "world") -> str:
        """Say hello to someone."""
        return f"Hello, {name}!"


    if __name__ == "__main__":
        mcp.run(transport="streamable-http")
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-mcp
spec:
  replicas: 1
  selector:
    matchLabels: { app: hello-mcp }
  template:
    metadata:
      labels: { app: hello-mcp }
    spec:
      containers:
        - name: hello-mcp
          image: python:3.13-slim
          command: ["sh", "-c", "pip install --quiet mcp && python /app/hello_server.py"]
          volumeMounts:
            - { name: src, mountPath: /app }
          ports:
            - { containerPort: 9000 }
      volumes:
        - name: src
          configMap: { name: hello-mcp-src }
---
apiVersion: v1
kind: Service
metadata:
  name: hello-mcp
spec:
  selector: { app: hello-mcp }
  ports:
    - { port: 9000, targetPort: 9000 }
EOF

以下安装步骤会注明在何处添加相应的路由。

安装

验证部署

从 Anthropic 端进行端到端验证：在 Managed Agent 会话或 Messages API 请求中使用 https://<route>.<your-tunnel-domain>/（其中 `` 是上游提供的路径）。有关请求格式，请参阅 使用隧道 MCP 服务器。

如果失败，请检查 Pod 日志（kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy 和 -c cloudflared）并查阅 故障排除。

可选配置

使用 NetworkPolicy 限制出站流量

默认情况下，代理 Pod 的入站流量被拒绝（networkPolicy.ingress.enabled: true）。要额外限制 Pod 出站流量，请设置 networkPolicy.egress.enabled: true 并将 networkPolicy.egress.mcpServers 填充为覆盖上游 MCP 服务器的 Pod 标签选择器或 CIDR 范围；cloudflared 到隧道边缘的出站流量通过 networkPolicy.egress.cloudflaredEgressCIDRs 允许。

调优代理

gateway.config.* 下的字段会透传到代理配置文件。常见调整包括 upstream.allowed_ips、log_level 和 upstream.tls。有关完整字段列表，请参阅 代理配置 参考。Chart 强制设置 listen_addr、tls.cert_file 和 tls.key_file；在 gateway.config 中设置它们无效。

提供您自己的 OIDC 令牌

默认情况下，chart 为 setup Job 投射一个 Kubernetes ServiceAccount 令牌。要使用来自不同身份提供商的令牌（SPIFFE、Vault、云 SDK sidecar），请使用 setup.extraVolumes / setup.extraVolumeMounts 挂载它，并将 api.wif.tokenFile 指向挂载路径。Setup 程序从 ANTHROPIC_IDENTITY_TOKEN_FILE 读取令牌，chart 会将其设置为该路径。

升级

始终向 helm upgrade 传递 --version，以避免意外拉取更新版本的 chart。

更改配置

对于路由、副本数或 NetworkPolicy 等常规更改：

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 1.0.0 \
  -n mcp-tunnel \
  -f values.yaml

轮换隧道令牌

使用编程访问时，在 values.yaml 中递增 tunnel.tokenVersion 并使用 --set setup.force=true 升级。Setup hook 仅在强制时才会在升级时重新运行：

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 1.0.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set setup.force=true

Setup Job 通过 Workload Identity Federation 进行身份验证；无需撤销 API 令牌。

不使用编程访问时，在控制台的隧道详情页上点击 Rotate token，然后更新 mcp-tunnel-token Secret：

kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \
  --from-literal=tunnel-token='eyJ...' --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel rollout restart deploy/mcp-tunnel

证书续期

Chart 提供自动化功能，但您仍有责任监控过期时间并确认续期完成。

使用编程访问时，证书续期是自动的。Chart 部署了一个 CronJob（<release>-cert-renew，每日在 serverCert.cronSchedule 时运行，默认为 0 0 * * * UTC），运行 setup renew-cert 并仅在证书在 serverCert.renewBefore（默认 30 天）内到期时续期。续期是本地的：使用 Secret 中存储的 CA 签发新证书，不进行 API 调用，只需要 chart 授予的 Kubernetes RBAC。代理从 Secret 挂载中热重载证书，因此无需重启 Deployment。

不使用编程访问时没有 CronJob。从安装后保留的 mcp-tunnel/ 目录中，使用现有 CA 签发新的服务器证书（不要重新生成 CA）：

export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key data/tls.key -out /tmp/server.csr \
  -subj "/CN=$\{TUNNEL_DOMAIN\}"
openssl x509 -req -in /tmp/server.csr \
  -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
  -out data/tls.crt -days 90 -extfile data/tls.ext

kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \
  --from-file=tls.crt=data/tls.crt --from-file=tls.key=data/tls.key \
  --dry-run=client -o yaml | kubectl apply -f -

代理从 Secret 挂载中热重载证书。

后续步骤