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

セットアップコンポーネントは、クラスターのprojected ServiceAccountトークンをフェデレーションルールを通じて交換し、トンネルトークンを取得し、CAとサーバー証明書を生成して、CAをAnthropicに登録します。毎日実行されるCronJobが必要に応じてサーバー証明書を更新するため、シークレットを手動で扱う必要はありません。

1. 1

   クラスター用にWorkload Identity Federationを設定する

   KubernetesでWIFを使用するに従って、クラスターのOIDC発行者を登録し、フェデレーションルールを作成します。セットアップコンポーネントは、リリースnamespace内の専用のServiceAccountで実行されます。正確な名前はHelmのfullname規則に従うため、mcp-tunnel以外のリリース名を使用する場合は、ルールを作成する前にhelm template <release> ... | 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

   トンネルが組織のデフォルト以外のワークスペースにある場合は、ルールのサービスアカウントをそのワークスペースに追加してください（Tunnels APIはサービスアカウントのワークスペースメンバーシップに基づいて認可を行います）。

   ルールのID（fdrl_...）を控えておいてください。これをapi.wif.federationRuleIdとして設定します。

2. 2

   デフォルト値を取得する

   helm show values \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 > values.yaml

   
3. 3

   トンネルのアタッチとルートを設定する

   values.yamlを編集し、api.wif.*キーにフェデレーションルールIDと組織IDを設定し、さらに各アップストリームMCPサーバーのroutesエントリを追加します。

   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.<your-tunnel-domain>とsearch.<your-tunnel-domain>でサーバーに到達します。一部のマネージドKubernetesディストリビューションは、標準のプライベート範囲外にService CIDRを割り当てます。ルートがクラスター内のServiceを対象とする場合は、アップストリームIP検証の説明に従って、ここにgateway.config.upstream.allowed_ipsを追加してください。

4. 4

   レンダリングされたマニフェストを確認する

   チャートをレンダリングし、組織の審査手順に従って出力を確認します。

   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

   
5. 5

   インストールする

   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がフックエラーで失敗した場合は、セットアップコンポーネントの認証失敗を参照してください。

   tunnel.idが空の場合、セットアップコンポーネントはフェデレーションルールが対象とするワークスペース（api.wif.workspaceIdを設定しない限り組織のデフォルトワークスペース）にトンネルを作成し、そのIDとドメインをmcp-tunnel Secretに保存します。検証に必要なドメインは、ConsoleのMCP tunnelsページ（platform.claude.com/settings/workspaces/default/mcp-tunnels）から開くトンネルの詳細ページで確認できます。サイドバーのワークスペースピッカーで、トンネルを含むワークスペースを選択してください。Secretからドメインを読み取ることもできます。

   kubectl -n mcp-tunnel get secret mcp-tunnel \
     -o jsonpath='{.data.tunnel-domain}' | base64 -d

   

   セットアップコンポーネントを再実行する場合（アップグレード時やトークンのローテーション時）、このSecretに保存されたトンネルIDが再利用されます。2つ目のトンネルが作成されることはありません。

このモード（setup.enabled: false）では、チャートはAPI呼び出しを行いません。セットアップコンポーネントは実行されず、cert-renew CronJobもありません。Workload Identity Federationを設定したくない場合は、この方法を使用してください。

1. 1

   トンネルトークンとドメインを取得する

   トンネルを作成し、Consoleからトンネルトークンを取得します。

2. 2

   CAとサーバー証明書を生成する

   プロキシはプレーンなWebSocketでリッスンし、内部TLSはここで生成する証明書を使用してそのストリーム内で伝送されます。証明書の要件で説明されているとおり、サーバー証明書のSANには*.<tunnel-domain>を含める必要があります。

   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 <<EOF
   subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
   authorityKeyIdentifier = keyid,issuer
   extendedKeyUsage = serverAuth
   EOF
   
   # CA によって署名されたサーバー証明書
   openssl req -newkey rsa:2048 -nodes \
     -keyout 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

   

   Consoleでdata/ca.crtを登録します。data/ca.keyは永続的かつ安全な場所に保管してください。更新時に新しいサーバー証明書に署名するために必要になります。

3. 3

   2つのSecretを作成する

   チャートは特定のキーを読み取ります。Secret名は設定可能ですが、キーは変更できません。次のnamespace作成コマンドは、namespaceがすでに存在する場合（たとえばサンプルMCPサーバーの手順で作成済みの場合）は何も行いません。

   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

   
4. 4

   デフォルト値を取得する

   helm show values \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 > values.yaml

   
5. 5

   手動プロビジョニング用の値を設定する

   values.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検証の説明に従って、ここにgateway.config.upstream.allowed_ipsを追加してください。

6. 6

   レンダリングされたマニフェストを確認する

   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

   
7. 7

   インストールする

   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

   