使用 Helm 部署 MCP 隧道

Anthropic Helm chart 将隧道堆栈作为单个 Deployment 安装，并将其附加到您在 Console 中创建的隧道。

开始之前

您需要：

• 在 Console 中创建的隧道。 首先完成创建隧道并记录隧道 ID（tnl_...）。对于手动配置，您还需要该步骤中的隧道令牌和隧道域名。
• chart 用于向 Tunnels API 进行身份验证的方式。
  • 编程式访问（推荐）。 setup 组件通过 "Workload Identity Federation"（工作负载身份联合）进行身份验证，获取隧道令牌，生成 CA，将其注册到 Anthropic，并将所有内容存储在 Secret 中。您需要一个作用域为 org:manage_tunnels 的联合规则。
  • 手动。 跳过编程式访问。您需要从 Console 获取隧道令牌，自行生成 CA 和服务器证书，在 Console 中注册 CA，并将凭据作为 Secret 提供给集群。
• 一个 Kubernetes 集群，您可以使用 helm 和 kubectl 向其部署。不使用编程式访问选项卡还需要使用 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>/<path>，其中 <route> 是 gateway.config.routes 中的一个键，<path> 是上游 MCP 服务器提供服务的路径。对于示例 MCP 服务器，即 https://echo.<your-tunnel-domain>/mcp。有关请求格式，请参阅使用隧道化的 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 组件投影 Kubernetes ServiceAccount 令牌。要使用来自其他身份提供商的令牌（例如 SPIFFE、Vault 或云 SDK sidecar），请使用 setup.extraVolumes 和 setup.extraVolumeMounts 挂载它。然后将 api.wif.tokenFile 指向挂载路径。chart 会将 ANTHROPIC_IDENTITY_TOKEN_FILE 设置为该路径，setup 组件从那里读取令牌。

升级

始终向 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 组件仅在强制时才会在升级期间重新运行：

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 组件使用 Workload Identity Federation 进行身份验证；没有需要撤销的 API 令牌。

不使用编程式访问时，在 Console 的隧道详情页面上点击 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（以 Helm fullname 命名，后缀为 -cert-renew），每天运行 setup renew-cert（在 serverCert.cronSchedule 指定的时间，默认为 0 0 * * * UTC）。除非证书距到期时间在 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 挂载点热重载证书。

后续步骤