使用 Helm 部署 MCP 通道

Anthropic Helm chart 會將通道堆疊安裝為單一 Deployment，並將其附加到您在 Console 中建立的通道。

開始之前

您需要：

• 在 Console 中建立的通道。 請先完成建立通道並記錄通道 ID（tnl_...）。若採用手動佈建，您還需要該步驟中的通道權杖和通道網域。
• 讓 chart 向 Tunnels API 進行驗證的方式。
  • 程式化存取（建議）。 設定元件會透過「Workload Identity Federation」（工作負載身分聯合）進行驗證、擷取通道權杖、產生 CA、向 Anthropic 註冊該 CA，並將所有內容儲存在 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 會為設定元件投影 Kubernetes ServiceAccount 權杖。若要使用來自其他身分提供者的權杖（例如 SPIFFE、Vault 或雲端 SDK sidecar），請使用 setup.extraVolumes 和 setup.extraVolumeMounts 掛載它，然後將 api.wif.tokenFile 指向掛載路徑。chart 會將 ANTHROPIC_IDENTITY_TOKEN_FILE 設為該路徑，設定元件會從那裡讀取權杖。

升級

請一律在 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 進行升級。設定元件只有在強制時才會在升級期間重新執行：

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

設定元件使用 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 天），否則該 job 不會執行任何動作。更新是在本機進行：該 job 會使用已儲存在 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 掛載點熱重新載入憑證。

後續步驟