HelmでMCPトンネルをデプロイする

Anthropic Helmチャートは、トンネルスタックを単一のDeploymentとしてインストールし、トンネルにアタッチします。トンネルは、チャートのセットアップフックが自動的に作成するもの、またはConsoleで作成した既存のトンネルのいずれかです。



はじめる前に

以下が必要です。

• トンネル。 プログラマティックアクセスを使用する場合、トンネルIDを指定しなければチャートのセットアップフックが自動的に作成します。代わりに既存のトンネルにアタッチするには、Consoleで作成してトンネルID（tnl_...）を記録してください。手動プロビジョニングは常にConsoleで作成したトンネルから始まります。その場合、トンネルトークンとトンネルドメインも必要です。
• チャートがTunnels APIに認証する方法。
  • プログラマティックアクセス（推奨）。 セットアップコンポーネントが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）への接続。完全なネットワーク要件を参照してください。
• 1つ以上の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を設定し、アップストリームMCPサーバーをカバーするPodラベルセレクターまたはCIDR範囲をnetworkPolicy.egress.mcpServersに設定します。cloudflaredからトンネルエッジへのエグレスは、networkPolicy.egress.cloudflaredEgressCIDRsを通じて別途許可されます。



プロキシをチューニングする

gateway.config.*配下のフィールドは、プロキシ設定ファイルにそのまま渡されます。一般的な調整には、upstream.allowed_ips、log_level、upstream.tlsがあります。フィールドの完全なリストについては、プロキシ設定リファレンスを参照してください。チャートは常にlisten_addr、tls.cert_file、tls.key_fileを設定するため、gateway.configでこれらを設定しても効果はありません。



独自のOIDCトークンを提供する

デフォルトでは、チャートはセットアップコンポーネント用にKubernetes ServiceAccountトークンをプロジェクトします。別のアイデンティティプロバイダー（SPIFFE、Vault、クラウドSDKサイドカーなど）のトークンを使用するには、setup.extraVolumesとsetup.extraVolumeMountsでマウントします。次に、api.wif.tokenFileをマウントパスに向けます。チャートはANTHROPIC_IDENTITY_TOKEN_FILEをそのパスに設定し、セットアップコンポーネントはそこからトークンを読み取ります。



アップグレード

予期せず新しいチャートを取得しないように、helm upgradeには常に--versionを渡してください。



チャート1.xからのアップグレード

チャート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



証明書の更新

チャートは自動化を提供しますが、有効期限の監視と更新の完了確認はユーザーの責任です。

プログラマティックアクセスを使用する場合、証明書の更新は自動です。チャートはCronJob（Helmのfullnameに-cert-renewサフィックスを付けた名前）をデプロイし、setup renew-certを毎日実行します（serverCert.cronScheduleで指定、デフォルトは0 0 * * * UTC）。このジョブは、証明書の有効期限がserverCert.renewBefore（デフォルト30日）以内でない限り何も行いません。更新はローカルで行われます。ジョブはSecretにすでに保存されているCAで新しい証明書に署名し、API呼び出しを行わず、チャートが付与する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マウントから証明書をホットリロードします。



次のステップ