使用 Helm 部署 MCP 通道

使用 Anthropic Helm chart 在 Kubernetes 叢集上安裝通道堆疊。

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

開始之前

您需要：

一個通道。 使用程式化存取時，若您未提供通道 ID，chart 的設定 hook 會為您建立一個通道；若要改為附加到既有通道，請在 Console 中建立通道並記下通道 ID（tnl_...）。手動佈建一律從 Console 建立的通道開始；您還需要該通道的通道權杖與通道網域。
讓 chart 向 Tunnels API 進行驗證的方式。
- 程式化存取（建議）。 設定元件會透過 Workload Identity Federation 進行驗證、擷取通道權杖、產生 CA、向 Anthropic 註冊該 CA，並將所有內容儲存在 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

後續的安裝步驟會註明在何處新增對應的路由。

安裝

設定元件會透過您的聯合規則交換叢集的投射 ServiceAccount 權杖、擷取通道權杖、產生 CA 和伺服器憑證，並向 Anthropic 註冊該 CA。每日執行的 CronJob 會視需要更新伺服器憑證，因此您無需手動處理任何機密。

為叢集設定 Workload Identity Federation
依照搭配 Kubernetes 使用 WIF 註冊您叢集的 OIDC 簽發者並建立聯合規則。設定元件會在發行版本命名空間中以其專屬的 ServiceAccount 執行；確切名稱遵循 Helm 的 fullname 慣例，因此若發行版本名稱不是 mcp-tunnel，請在建立規則前執行 helm template <release> ... | grep -A2 'kind: ServiceAccount' 加以確認。本指南其餘部分假設發行版本名稱為 mcp-tunnel、命名空間為 mcp-tunnel，此時 ServiceAccount 為 mcp-tunnel-setup。
欄位值
Subject system:serviceaccount:mcp-tunnel:mcp-tunnel-setup
Audience api.anthropic.com（chart 的預設值；不含 scheme）
Scope workspace:manage_tunnels
chart 的預設 audience 是不含 scheme 的 api.anthropic.com，但 Console 的聯合規則表單建議使用 https://api.anthropic.com。兩者必須逐位元組相符，否則驗證會失敗。請將規則的 audience 設為 api.anthropic.com，或在 values.yaml 中將 api.wif.audience 設為 https://api.anthropic.com。
如果通道位於組織預設工作區以外的工作區，還需將規則的服務帳戶新增至該工作區（Tunnels API 會依據服務帳戶的工作區成員資格進行授權）。
記下規則的 ID（fdrl_...）；您會將其設為 api.wif.federationRuleId。
每日憑證更新 CronJob 使用另一個 ServiceAccount（同樣衍生自 Helm fullname），但不會呼叫 Tunnels API；它會在本機更新憑證，只需要 chart 授予的 Kubernetes RBAC。聯合規則不需要涵蓋它。

欄位	值
Subject	`system:serviceaccount:mcp-tunnel:mcp-tunnel-setup`
Audience	`api.anthropic.com`（chart 的預設值；不含 scheme）
Scope	`workspace:manage_tunnels`

擷取預設值

helm show values \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.1.0 > values.yaml

設定通道附加與路由

編輯 values.yaml，以聯合規則 ID 和組織 ID 設定 api.wif.* 鍵，並為每個上游 MCP 伺服器新增一個 routes 項目：

values.yaml

api:
  wif:
    federationRuleId: "fdrl_..."
    organizationId: "00000000-0000-0000-0000-000000000000"
    # Set when the tunnel is in a non-default workspace and the
    # rule's service account is a member of that workspace.
    # workspaceId: "wrkspc_..."

tunnel:
  # Leave empty to have the setup hook create a tunnel during install.
  # Set to attach to an existing tunnel from the Console.
  id: ""
  # Increment to rotate the tunnel token on the next upgrade.
  # See the "Rotate the tunnel token" section.
  tokenVersion: "1"

gateway:
  config:
    routes:
      docs: http://docs-mcp.internal:8080
      search: http://search-mcp.internal:8080

使用這些路由後，Claude 會透過 docs.<your-tunnel-domain> 和 search.<your-tunnel-domain> 連線到這些伺服器。部分受管 Kubernetes 發行版會在標準私有範圍之外配置 Service CIDR；如果您的路由指向叢集內的 Service，請依照上游 IP 驗證中的說明，在此新增 gateway.config.upstream.allowed_ips。

檢閱轉譯後的資訊清單

轉譯 chart，並依照您組織的審查慣例檢閱輸出：

helm template mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.1.0 \
  -n mcp-tunnel \
  -f values.yaml > rendered.yaml

5
安裝
helm install mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml
設定元件會以 Helm pre-install hook Job 的形式執行，因此 helm install 會阻塞直到其完成。成功後 Helm 會自動刪除該 Job。如果 helm install 因 hook 錯誤而失敗，請參閱設定元件驗證失敗。
當 tunnel.id 為空時，設定元件會在您的聯合規則所指向的工作區中建立通道（除非您設定了 api.wif.workspaceId，否則為組織的預設工作區），並將其 ID 和網域儲存在 mcp-tunnel Secret 中。您可以在通道的詳細資料頁面上找到驗證所需的網域，該頁面可從 Console 中的 MCP tunnels 頁面（platform.claude.com/settings/workspaces/default/mcp-tunnels）開啟。在側邊欄的工作區選擇器中，選取包含該通道的工作區。您也可以從 Secret 讀取網域：
kubectl -n mcp-tunnel get secret mcp-tunnel \ -o jsonpath='{.data.tunnel-domain}' | base64 -d
重新執行設定元件時（在升級或權杖輪替期間），會重複使用儲存在此 Secret 中的通道 ID；它絕不會建立第二個通道。
api.wif.* 值是識別碼而非機密，因此將其儲存在 Helm 發行版本歷史記錄 Secret 中並無風險。靜態儲存的敏感資料是設定元件建立的 mcp-tunnel Secret，其中包含通道權杖和 TLS 私密金鑰。請對此命名空間套用您組織保護 Kubernetes Secret 的標準做法。

在此模式下（setup.enabled: false），chart 不會發出任何 API 呼叫；設定元件不會執行，也沒有 cert-renew CronJob。如果您不想設定 Workload Identity Federation，請使用此路徑。

取得通道權杖和網域
建立通道並從 Console 取得通道權杖。
從詳細資料頁面記下通道網域。您會將其設為 gateway.config.tunnel_domain。

產生 CA 和伺服器憑證

代理伺服器以純 WebSocket 監聽，內層 TLS 則使用您在此產生的憑證在該串流中傳輸。伺服器憑證的 SAN 必須包含 *.<tunnel-domain>，如憑證需求中所述。

export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
mkdir -p mcp-tunnel/data
cd mcp-tunnel

# 自簽 CA。明確指定擴充欄位，使其符合憑證
# 要求，不受各發行版 openssl.cnf 預設值影響。
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout data/ca.key -out data/ca.crt \
  -days 3650 -subj "/CN=mcp-tunnel-ca" \
  -addext "basicConstraints=critical,CA:TRUE" \
  -addext "keyUsage=critical,keyCertSign,cRLSign" \
  -addext "subjectKeyIdentifier=hash"

# 伺服器憑證的擴充欄位檔案。使用 -extfile（而非
# 僅 OpenSSL 3.0+ 支援的 -copy_extensions）可確保在
# OpenSSL 1.1.x 上仍能運作。
cat > data/tls.ext <<EOF
subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
authorityKeyIdentifier = keyid,issuer
extendedKeyUsage = serverAuth
EOF

# 由 CA 簽署的伺服器憑證
openssl req -newkey rsa:2048 -nodes \
  -keyout 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

在 Console 中註冊 data/ca.crt。請將 data/ca.key 保存在持久且安全的位置；在更新時您需要用它來簽署新的伺服器憑證。

建立兩個 Secret

chart 會讀取特定的鍵；Secret 名稱可以設定，但鍵不行。如果命名空間已存在（例如來自範例 MCP 伺服器步驟），以下建立命名空間的命令不會有任何作用。

kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \
  --from-literal=tunnel-token='eyJ...'
kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \
  --from-file=tls.crt=data/tls.crt \
  --from-file=tls.key=data/tls.key

擷取預設值

helm show values \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.1.0 > values.yaml

設定手動佈建的值

編輯 values.yaml 並設定以下鍵：

values.yaml

setup:
  enabled: false

external:
  tunnelTokenSecretName: mcp-tunnel-token   # must contain key: tunnel-token
  serverCertSecretName: mcp-tunnel-cert     # must contain keys: tls.crt, tls.key

gateway:
  config:
    # Required when setup.enabled is false. Replace the placeholder with
    # the $TUNNEL_DOMAIN value you exported earlier. When setup.enabled
    # is true the chart injects this from the Secret as a -tunnel-domain
    # flag instead.
    tunnel_domain: YOUR_TUNNEL_DOMAIN_HERE
    routes:
      docs: http://docs-mcp.internal:8080
      search: http://search-mcp.internal:8080

部分受管 Kubernetes 發行版會在標準私有範圍之外配置 Service CIDR；如果您的路由指向叢集內的 Service，請依照上游 IP 驗證中的說明，在此新增 gateway.config.upstream.allowed_ips。

檢閱轉譯後的資訊清單

helm template mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.1.0 \
  -n mcp-tunnel \
  -f values.yaml > rendered.yaml

安裝

helm install mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.1.0 \
  --namespace mcp-tunnel --create-namespace \
  -f values.yaml

驗證部署

從 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.1.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 2.1.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，預設為 UTC 0 0 * * *）。除非憑證距離到期時間在 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 掛載熱重新載入憑證。

後續步驟

使用透過通道連線的 MCP 伺服器

將上游 MCP 伺服器附加到 Managed Agent 或 Messages API。

安全性

強化指引、憑證輪替與入侵應變。

疑難排解

診斷連線、TLS 和路由問題。

開始之前

選用：使用範例 MCP 伺服器

安裝

為叢集設定 Workload Identity Federation

擷取預設值

設定通道附加與路由

檢閱轉譯後的資訊清單

安裝

取得通道權杖和網域

產生 CA 和伺服器憑證

建立兩個 Secret

擷取預設值

設定手動佈建的值

檢閱轉譯後的資訊清單

安裝

驗證部署

選用設定

使用 NetworkPolicy 限制對外流量

調整代理

提供您自己的 OIDC 權杖

升級

從 chart 1.x 升級

變更設定

輪替通道權杖

憑證更新

後續步驟

開始之前

選用：使用範例 MCP 伺服器

安裝

驗證部署

選用設定

使用 NetworkPolicy 限制對外流量

調整代理

提供您自己的 OIDC 權杖

升級

從 chart 1.x 升級

變更設定

輪替通道權杖

憑證更新

後續步驟