--- 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としてインストールし、トンネルにアタッチします。アタッチ先は、チャートのセットアップフックが作成するトンネル、または[Claude 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発行者を登録し、フェデレーションルールを作成します。セットアップコンポーネントは、リリースnamespace内の専用のServiceAccountで実行されます。正確な名前はHelmの`fullname`規則に従うため、`mcp-tunnel`以外のリリース名を使用する場合は、ルールを作成する前に`helm template ... | grep -A2 'kind: ServiceAccount'`を実行して確認してください。このガイドの残りの部分では、namespace `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.1.0 > 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.1.0 \ -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.1.0 \ --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秘密鍵を保持しています。このnamespaceには、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)はここで生成する証明書を使用してそのストリーム内で伝送されます。[証明書の要件](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/reference#certificate-requirements)で説明されているとおり、サーバー証明書のSANには`*.`を含める必要があります。 ```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名は設定可能ですが、キーは変更できません。次のnamespace作成コマンドは、namespaceがすでに存在する場合（たとえば[サンプル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.1.0 > 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.1.0 \ -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.1.0 \ --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で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`があります。フィールドの完全な一覧については、[プロキシ設定](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トークンをprojectします。別の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.1.0 \ -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.1.0 \ -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`、デフォルトはUTCの`0 0 * * *`）実行する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、ルーティングの問題を診断します。