使用 Helm 部署 MCP 通道

Anthropic Helm chart 會將通道堆疊安裝為單一 Deployment，並將其附加到您的通道：可以是 chart 的設定掛鉤（setup hook）為您建立的通道，或是您在 Console 中建立的現有通道。



開始之前

您需要：

• 一個通道。 使用程式化存取時，如果您未提供通道 ID，chart 的設定掛鉤會為您建立一個；若要改為附加到現有通道，請在 Console 中建立它並記錄通道 ID（tnl_...）。手動佈建一律從 Console 建立的通道開始；您還需要其通道權杖（tunnel token）和通道網域（tunnel domain）。
• 讓 chart 向 Tunnels API 進行驗證的方式。
  • 程式化存取（建議）。 設定元件透過 Workload Identity Federation 進行驗證、擷取通道權杖、產生 CA、向 Anthropic 註冊，並將所有內容儲存在 Secret 中。您需要一個範圍限定為 workspace:manage_tunnels 的聯合規則（federation rule）。
  • 手動。 跳過程式化存取。您將從 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 會為設定元件投射一個 Kubernetes ServiceAccount 權杖。若要使用來自不同身分提供者的權杖（例如 SPIFFE、Vault 或雲端 SDK sidecar），請使用 setup.extraVolumes 和 setup.extraVolumeMounts 掛載它。然後將 api.wif.tokenFile 指向掛載路徑。chart 會將 ANTHROPIC_IDENTITY_TOKEN_FILE 設為該路徑，設定元件會從那裡讀取權杖。



升級

一律將 --version 傳遞給 helm upgrade，以免意外拉取較新的 chart。



從 chart 1.x 升級

Chart 2.0.0 將通道 ID 從 api.wif.tunnelId 移至 tunnel.id。升級前，請編輯您的 values.yaml：將 tnl_... 值移至 tunnel.id 並移除 api.wif.tunnelId。不設定 tunnel.id 是安全的（設定元件在重新執行時會重複使用已儲存在 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 進行升級。設定元件只有在強制時才會在升級時重新執行：

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

設定元件使用 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 掛載熱重載憑證。



後續步驟