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としてクラスターに提供します。
• helmとkubectlでデプロイできるKubernetesクラスター。プログラムによるアクセスなしタブではopenssl（1.1.1以降）も使用します。
• クラスターからapi.anthropic.com（443 TCP）およびトンネルエッジ（7844 TCPおよびUDP）へのアウトバウンドネットワーク接続。完全なネットワーク要件を参照してください。
• gateway.config.routesで設定するアドレスでクラスターから到達可能な、稼働中の1つ以上のMCPサーバー。まだない場合は、サンプルサーバーを使用してください。



オプション：サンプル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でegressを制限する

プロキシPodへのingressはデフォルトで拒否されます（networkPolicy.ingress.enabled: true）。さらにPodのegressを制限するには、networkPolicy.egress.enabled: trueを設定し、アップストリームMCPサーバーをカバーするPodラベルセレクターまたはCIDR範囲をnetworkPolicy.egress.mcpServersに設定します。cloudflaredからトンネルエッジへのegressは、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トークンを投影します。別のIDプロバイダー（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.2 \
  -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.2 \
  -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



証明書の更新

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

プログラムによるアクセスを使用している場合、証明書の更新は自動です。チャートは、setup renew-certを毎日（serverCert.cronScheduleで、デフォルトは0 0 * * * UTC）実行するCronJob（Helmのfullnameに-cert-renewサフィックスを付けた名前）をデプロイします。このジョブは、証明書の有効期限が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マウントから証明書をホットリロードします。



次のステップ