使用 Helm 部署 MCP 通道

Anthropic Helm chart 會將通道堆疊（tunnel stack）安裝為單一 Deployment，並將其附加到您的通道：可以是 chart 的 setup hook 為您建立的通道，也可以是您在 Console 中建立的既有通道。

開始之前

您需要：

• 一個通道。 使用程式化存取時，若您未提供通道 ID，chart 的 setup hook 會為您建立一個；若要改為附加到既有通道，請在 Console 中建立它並記下通道 ID（tnl_...）。手動佈建一律從 Console 建立的通道開始；您還需要它的通道權杖（tunnel token）與通道網域（tunnel domain）。
• 讓 chart 向 Tunnels API 進行驗證的方式。
  • 程式化存取（Programmatic access）（建議）。 setup 元件透過 Workload Identity Federation 進行驗證、擷取通道權杖、產生 CA、向 Anthropic 註冊該 CA，並將所有內容儲存在一個 Secret 中。您需要一條範圍限定為 workspace:manage_tunnels 的 federation rule。
  • 手動（Manual）。 略過程式化存取。您將從 Console 取得通道權杖、自行產生 CA 與伺服器憑證、在 Console 中註冊 CA，並以 Secret 的形式將憑證提供給叢集。
• 一個 Kubernetes 叢集，您可以使用 helm 與 kubectl 部署至該叢集。不使用程式化存取分頁還會用到 openssl（1.1.1 或更新版本）。
• 對外網路連線能力，從叢集連至 api.anthropic.com（443 TCP）以及通道邊緣（tunnel edge）（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 限制對外流量

預設會拒絕進入 proxy pod 的流量（networkPolicy.ingress.enabled: true）。若要進一步限制 pod 的對外流量，請設定 networkPolicy.egress.enabled: true，並在 networkPolicy.egress.mcpServers 中填入涵蓋您上游 MCP 伺服器的 pod 標籤選擇器或 CIDR 範圍。從 cloudflared 到通道邊緣的對外流量則透過 networkPolicy.egress.cloudflaredEgressCIDRs 另行允許。

調整 proxy

gateway.config.* 下的欄位會直接傳遞至 proxy 設定檔。常見的調整包括 upstream.allowed_ips、log_level 與 upstream.tls。完整欄位清單請參閱 proxy 設定參考文件。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 元件會從該處讀取權杖。

升級

請一律將 --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 是安全的（setup 元件重新執行時會重複使用已儲存在 mcp-tunnel Secret 中的通道 ID），但明確搬移可讓您的 values.yaml 保持準確。也請在 Console 中將 federation rule 的範圍從 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.2 \
  -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.2 \
  -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。proxy 會從 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 -

proxy 會從 Secret 掛載熱重新載入憑證。

後續步驟