--- title: Helm を使用して MCP トンネルをデプロイする url: https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/deploy-helm description: Anthropic の Helm チャートを使用して、Kubernetes クラスターにトンネルスタックをインストールします。 --- MCPトンネルはリサーチプレビュー段階です。お試しいただくには、[アクセスをリクエスト](https://claude.com/form/mcp-tunnels)してください。 Anthropic の Helm チャートは、[トンネルスタック](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/concepts#components)を単一の Deployment としてインストールし、トンネルに接続します。接続先は、チャートのセットアップフックが作成するトンネル、または [Console](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/console#create-a-tunnel) で作成した既存のトンネルのいずれかです。 ## 始める前に 以下が必要です。 * **トンネル。** プログラムによるアクセスを使用する場合、トンネル ID を指定しなければチャートのセットアップフックがトンネルを作成します。代わりに既存のトンネルに接続するには、[Console でトンネルを作成](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/console#create-a-tunnel)し、トンネル ID（`tnl_...`）を記録してください。手動プロビジョニングは常に Console で作成したトンネルから始まります。その場合、トンネルトークンとトンネルドメインも必要です。 * **チャートが Tunnels API に対して認証する手段。** * **[プログラムによるアクセス](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/concepts#credential-provisioning)（推奨）。** [セットアップコンポーネント](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/concepts#components)が Workload Identity Federation を通じて認証し、トンネルトークンを取得し、CA を生成して Anthropic に登録し、すべてを Secret に保存します。`workspace:manage_tunnels` にスコープされたフェデレーションルールが必要です。 * **[手動](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/concepts#credential-provisioning)。** プログラムによるアクセスを省略します。[Console からトンネルトークンを取得](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/console#get-the-connection-details)し、CA とサーバー証明書を自分で生成し、[Console で CA を登録](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate)して、認証情報を Secret としてクラスターに提供します。 * `helm` と `kubectl` でデプロイできる **Kubernetes クラスター**。**プログラムによるアクセスなし** タブでは `openssl`（1.1.1 以降）も使用します。 * クラスターから `api.anthropic.com`（443 TCP）および[トンネルエッジ](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/concepts#components)（7844 TCP および UDP）への **アウトバウンドネットワーク接続**。完全な[ネットワーク要件](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/overview#network-requirements)を参照してください。 * `gateway.config.routes` で設定するアドレスでクラスターから到達可能な、稼働中の **1 つ以上の MCP サーバー**。まだ用意していない場合は、[サンプルサーバーを使用](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server)してください。 ## オプション: サンプル MCP サーバーを使用する テスト用の MCP サーバーがない場合は、この最小限のサーバーを使用してください。 ```bash 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 ``` 以降のインストール手順では、対応するルートを追加する箇所を示しています。 ## インストール セットアップコンポーネントは、クラスターの projected ServiceAccount トークンをフェデレーションルールを通じて交換し、トンネルトークンを取得し、CA とサーバー証明書を生成して、CA を Anthropic に登録します。日次の CronJob が必要に応じてサーバー証明書を更新するため、シークレットを手動で扱う必要はありません。 [Kubernetes で WIF を使用する](https://platform.claude.com/docs/ja/manage-claude/wif-providers/kubernetes)に従って、クラスターの OIDC 発行者を登録し、フェデレーションルールを作成します。セットアップコンポーネントはリリース名前空間内の専用の ServiceAccount で実行されます。正確な名前は Helm の `fullname` 規則に従うため、`mcp-tunnel` 以外のリリース名を使用する場合は、ルールを作成する前に `helm template ... | grep -A2 'kind: ServiceAccount'` を実行して確認してください。このガイドの残りの部分では、名前空間 `mcp-tunnel` 内のリリース名 `mcp-tunnel` を前提とし、その場合の ServiceAccount は `mcp-tunnel-setup` です。 | フィールド | 値 | | -------- | --------------------------------------------------- | | Subject | `system:serviceaccount:mcp-tunnel:mcp-tunnel-setup` | | Audience | `api.anthropic.com`（チャートのデフォルト。スキームなし） | | Scope | `workspace:manage_tunnels` | チャートのデフォルトの audience はスキームなしの `api.anthropic.com` ですが、Console のフェデレーションルールフォームは `https://api.anthropic.com` を提案します。この 2 つはバイト単位で一致する必要があり、一致しないと認証に失敗します。ルールの audience を `api.anthropic.com` に設定するか、`values.yaml` の `api.wif.audience` を `https://api.anthropic.com` に設定してください。 トンネルが組織のデフォルト以外のワークスペースにある場合は、[ルールのサービスアカウントをそのワークスペースにも追加](https://platform.claude.com/docs/ja/manage-claude/workspaces#role-inheritance)してください（Tunnels API はサービスアカウントのワークスペースメンバーシップに基づいて認可を行います）。 ルールの ID（`fdrl_...`）を控えておいてください。これを `api.wif.federationRuleId` として設定します。 日次の証明書更新 CronJob は別の ServiceAccount（これも Helm の `fullname` から派生）を使用しますが、Tunnels API は呼び出しません。証明書をローカルで更新し、チャートが付与する Kubernetes RBAC のみを必要とします。フェデレーションルールでこれをカバーする必要はありません。 ```bash helm show values \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 > values.yaml ``` `values.yaml` を編集し、`api.wif.*` キーにフェデレーションルール ID と組織 ID を設定し、さらに各[アップストリーム MCP サーバー](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/concepts#components)ごとに `routes` エントリを追加します。 ```yaml 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.` および `search.` でサーバーに到達します。一部のマネージド Kubernetes ディストリビューションは、Service CIDR を標準のプライベート範囲外に割り当てます。ルートがクラスター内の Service を対象とする場合は、[アップストリーム IP 検証](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation)に従って、ここに `gateway.config.upstream.allowed_ips` を追加してください。 [サンプル MCP サーバー](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server)を使用している場合は、代わりに `routes` を `echo: http://hello-mcp:9000` に設定してください。 チャートをレンダリングし、組織の審査手順に従って出力を確認します。 ```bash helm template mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ -n mcp-tunnel \ -f values.yaml > rendered.yaml ``` ```bash helm install mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml ``` セットアップコンポーネントは Helm の pre-install フック Job として実行されるため、`helm install` は完了するまでブロックされます。成功すると Helm は Job を自動的に削除します。`helm install` がフックエラーで失敗した場合は、[セットアップコンポーネントの認証失敗](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/troubleshooting#setup-component-authentication-failures)を参照してください。 `tunnel.id` が空の場合、セットアップコンポーネントはフェデレーションルールが対象とするワークスペース（`api.wif.workspaceId` を設定しない限り組織のデフォルトワークスペース）にトンネルを作成し、その ID とドメインを `mcp-tunnel` Secret に保存します。[検証](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/deploy-helm#verify-the-deployment)に必要なドメインは、Console の [MCP tunnels](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) ページ（`platform.claude.com/settings/workspaces/default/mcp-tunnels`）から開くトンネルの詳細ページで確認できます。サイドバーのワークスペースピッカーで、トンネルを保持するワークスペースを選択してください。Secret からドメインを読み取ることもできます。 ```bash kubectl -n mcp-tunnel get secret mcp-tunnel \ -o jsonpath='{.data.tunnel-domain}' | base64 -d ``` セットアップコンポーネントを再実行しても（[アップグレード](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/deploy-helm#upgrades)や[トークンのローテーション](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/deploy-helm#rotate-the-tunnel-token)の際）、この Secret に保存されたトンネル ID が再利用されます。2 つ目のトンネルが作成されることはありません。 `api.wif.*` の値は識別子でありシークレットではないため、Helm のリリース履歴 Secret に保存してもリスクはありません。保存時に機密となるデータは、セットアップコンポーネントが作成する `mcp-tunnel` Secret であり、トンネルトークンと TLS 秘密鍵を保持しています。この名前空間には、Kubernetes Secret を保護するための組織の標準的な手順を適用してください。 このモード（`setup.enabled: false`）では、チャートは API 呼び出しを一切行いません。セットアップコンポーネントは実行されず、cert-renew CronJob もありません。Workload Identity Federation を設定したくない場合は、この方法を使用してください。 [トンネルを作成](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/console#create-a-tunnel)し、[Console からトンネルトークンを取得](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/console#get-the-connection-details)します。 詳細ページからトンネルドメインを記録してください。これを `gateway.config.tunnel_domain` として設定します。 プロキシはプレーンな WebSocket でリッスンし、ここで生成する証明書を使用した[内部 TLS](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/concepts#components) がそのストリーム内で運ばれます。サーバー証明書の SAN には、[証明書の要件](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/reference#certificate-requirements)に従って `*.` を含める必要があります。 ```bash 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 < チャートは特定のキーを読み取ります。Secret 名は設定可能ですが、キーは変更できません。以下の名前空間作成コマンドは、名前空間がすでに存在する場合（たとえば[サンプル MCP サーバー](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server)の手順で作成済みの場合）は何も行いません。 ```bash 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 ``` ```bash helm show values \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 > values.yaml ``` `values.yaml` を編集し、以下のキーを設定します。 ```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 検証](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation)に従って、ここに `gateway.config.upstream.allowed_ips` を追加してください。 [サンプル MCP サーバー](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server)を使用している場合は、代わりに `routes` を `echo: http://hello-mcp:9000` に設定してください。 ```bash helm template mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ -n mcp-tunnel \ -f values.yaml > rendered.yaml ``` ```bash helm install mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml ``` ## デプロイを検証する Anthropic 側からエンドツーエンドで検証します。Managed Agent セッションまたは Messages API リクエストで `https://./` を使用してください。ここで `` は `gateway.config.routes` のキー、`` はアップストリーム MCP サーバーが提供するパスです。[サンプル MCP サーバー](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server)の場合は `https://echo./mcp` です。リクエストの形式については、[トンネル経由の MCP サーバーを使用する](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers)を参照してください。 失敗した場合は、Pod のログ（`kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy` および `-c cloudflared`）を確認し、[トラブルシューティング](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/troubleshooting)を参照してください。 ## オプションの設定 ### 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` があります。フィールドの完全な一覧については、[プロキシ設定](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/reference#proxy-configuration)リファレンスを参照してください。チャートは常に `listen_addr`、`tls.cert_file`、`tls.key_file` を設定するため、これらを `gateway.config` で設定しても効果はありません。 ### 独自の OIDC トークンを提供する デフォルトでは、チャートはセットアップコンポーネント用に Kubernetes ServiceAccount トークンを投影します。別の ID プロバイダー（[SPIFFE](https://platform.claude.com/docs/ja/manage-claude/wif-providers/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 などの日常的な変更の場合: ```bash 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 ``` `--reuse-values` に頼るのではなく、完全な `values.yaml` を維持してください。Helm のディープマージの動作により、削除したルートが気付かないうちに削除されないままになることがあります。 ### トンネルトークンをローテーションする プログラムによるアクセスを使用している場合は、`values.yaml` の `tunnel.tokenVersion` をインクリメントし、`--set setup.force=true` を付けてアップグレードします。セットアップコンポーネントは、強制された場合にのみアップグレード時に再実行されます。 ```bash 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 を更新します。 ```bash 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 ``` **Rotate token** をクリックすると、現在のトークンは即座に無効になります。Secret が更新されロールアウトが完了するまでの間、古いトークンで再起動した Pod（エビクション、ノードのドレイン、OOM）は再接続できません。ローテーション後は速やかに Secret を更新してください。より厳格な可用性要件がある場合は、チャートがローテーションをアトミックに処理できるよう、プログラムによるアクセスを使用してください。 ### 証明書の更新 チャートは自動化を提供しますが、有効期限の監視と更新完了の確認は引き続きお客様の責任です。 プログラムによるアクセスを使用している場合、証明書の更新は自動です。チャートは、`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 は再生成しないでください）。 ```bash 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 サーバーを Managed Agent または Messages API に接続します。 ハードニングのガイダンス、認証情報のローテーション、侵害への対応。 接続、TLS、ルーティングの問題を診断します。