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 でエグレスを制限する

プロキシ 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 トークンを投影します。別の 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 マウントから証明書をホットリロードします。

次のステップ