使用 Helm 部署 MCP 隧道

Anthropic Helm chart 将隧道堆栈作为单个 Deployment 安装，并将其附加到您的隧道：可以是 chart 的 setup hook 为您创建的隧道，也可以是您在 Console 中创建的现有隧道。



开始之前

您需要：

• 一个隧道。 使用程序化访问时，如果您不提供隧道 ID，chart 的 setup hook 会为您创建一个；如果要附加到现有隧道，请在 Console 中创建它并记录隧道 ID（tnl_...）。手动配置始终从 Console 创建的隧道开始；您还需要其隧道令牌和隧道域名。
• chart 向 Tunnels API 进行身份验证的方式。
  • 程序化访问（推荐）。 setup 组件通过 Workload Identity Federation 进行身份验证，获取隧道令牌，生成 CA，将其注册到 Anthropic，并将所有内容存储在 Secret 中。您需要一个作用域为 workspace: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。



从 chart 1.x 升级

Chart 2.0.0 将隧道 ID 从 api.wif.tunnelId 移至 tunnel.id。升级前，请编辑您的 values.yaml：将 tnl_... 值移至 tunnel.id 并删除 api.wif.tunnelId。不设置 tunnel.id 是安全的（setup 组件在重新运行时会重用已存储在 mcp-tunnel Secret 中的隧道 ID），但显式移动可以保持您的 values.yaml 准确。另外，请在 Console 中将联合规则的作用域从 org:manage_tunnels 更新为 workspace:manage_tunnels。



更改配置

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

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.0.1 \
  -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 2.0.1 \
  -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 挂载中热重载证书。



后续步骤