--- title: MCPトンネルリファレンス url: https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/reference description: プロキシ設定フィールド、Tunnels REST API、証明書の要件、およびセットアップコンポーネント。 --- MCPトンネルはリサーチプレビュー段階です。お試しいただくには、[アクセスをリクエスト](https://claude.com/form/mcp-tunnels)してください。 ## プロキシ設定 [プロキシ](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/concepts#components)は、`/etc/mcp-gateway/config.yaml`（Compose）またはレンダリングされたConfigMap（Helm、`gateway.config.*` から生成）から設定を読み込みます。 | フィールド | 説明 | デフォルト | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | `listen_addr` | リッスンするアドレスとポート。 | 必須 | | `log_level` | ログの詳細度：`debug`、`info`、`warn`、または `error`。 | `info` | | `shutdown_timeout` | グレースフルシャットダウン中に処理中のリクエストを待機する時間。 | `30s` | | `tunnel_domain` | トンネルに割り当てられたベースドメイン。設定されている場合、ルート検索は受信ホスト名からこのサフィックスを取り除くため、`routes` のキーをサブドメインのみ（`wiki`）にできます。空の場合、`routes` のキーは完全なホスト名と正確に一致する必要があります。 | `routes` のキーがサブドメインのみの場合は必須 | | `tls.cert_file` | サーバーTLS証明書へのパス。 | 必須 | | `tls.key_file` | サーバーTLS秘密鍵へのパス。 | 必須 | | `routes` | サブドメインまたは完全なホスト名からアップストリームURLへのマップ。[ルートマッチング](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/reference#route-matching)を参照してください。 | 必須 | | `upstream.allowed_ips` | プロキシが接続を許可されるIPv4 CIDR範囲または単一アドレス。`disable_ip_validation` とは相互排他です。 | RFC1918プライベート範囲 | | `upstream.disable_ip_validation` | アップストリームIP検証を完全に無効化します。`allowed_ips` とは相互排他です。 | `false` | | `upstream.tls.ca_file` | アップストリームTLSを検証するためのCAバンドル。 | なし | | `upstream.tls.include_system_cas` | アップストリームTLSに対してシステムCAバンドルも信頼します。 | `false` | `https://` のアップストリームルートの場合、`upstream.tls.ca_file` または `upstream.tls.include_system_cas` の少なくとも一方を設定してください。設定しない場合、プロキシはアップストリーム証明書に対するトラストアンカーを持ちません。 ### ルートマッチング `routes` はリストではなく、フラットな文字列マップ（`map[string]string`）です。プロキシはまず受信ホスト名を完全一致で検索し、次に `tunnel_domain` サフィックスを取り除いて残りのサブドメインで照合します。照合ではホスト名のみが考慮され、リクエストパスとクエリ文字列は変更されずに[アップストリームMCPサーバー](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/concepts#components)に転送されます。 各アップストリーム値は正確に `scheme://host:port` の形式である必要があります。ポートは必須です。パスを含めると、設定の読み込み時に `invalid upstream (must be scheme://host:port)` で拒否されます。 ## Tunnels API Tunnels REST APIは `/v1/tunnels` にあり、トンネルの作成、一覧表示、アーカイブ、CA証明書の登録、およびトンネルトークンの表示またはローテーションをサポートします。すべてのエンドポイント、リクエストおよびレスポンスのスキーマ、例については、[Tunnels APIリファレンス](https://platform.claude.com/docs/ja/api/beta/tunnels/list)を参照してください。 以前のAdmin APIサーフェスである `/v1/organizations/tunnels`（ベータヘッダー `mcp-tunnels-2026-05-19`、スコープ `org:manage_tunnels`）は移行期間中も 引き続き動作し、非推奨の通知とともに [Admin APIリファレンス](https://platform.claude.com/docs/ja/api/beta/organization/mcp_tunnels)に記載されています。 移行するには、パスを `/v1/tunnels` に、ベータヘッダーを `mcp-tunnels-2026-06-22` に、WIFトークンのスコープを `workspace:manage_tunnels` に更新してください。 すべてのMCPトンネルエンドポイントには、[Workload Identity Federation](https://platform.claude.com/docs/ja/manage-claude/workload-identity-federation)を通じて取得した `workspace:manage_tunnels` スコープを持つベアラートークンが必要です。Admin APIキーは受け付けられません。 すべてのリクエストに必要なヘッダー： | ヘッダー | 値 | | ------------------- | ------------------------------- | | `Authorization` | `Bearer `（WIFで交換されたトークン） | | `anthropic-version` | `2023-06-01` | | `anthropic-beta` | `mcp-tunnels-2026-06-22` | ## 証明書の要件 [セットアップコンポーネント](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/concepts#components)は、準拠した証明書を自動的に生成します。これらの要件は、独自のPKIを通じて証明書を発行する場合にのみ適用されます。 ### CA証明書 `POST /v1/tunnels/{tunnel_id}/certificates` でアップロードします。トンネルは同時に最大2つのアクティブなCA証明書を保持でき、これによりダウンタイムなしのローテーションが可能になります。 * PEMエンコード、単一の証明書、最大8 kB。 * `BasicConstraints` 拡張が存在し、`CA:TRUE` で、criticalとしてマークされていること。 * `SubjectKeyIdentifier` 拡張が存在すること。 * `KeyUsage` に `keyCertSign` が含まれること。 * 有効期間内であること。 * RSA 2048ビット以上、またはECDSA P-256以上で、SHA-256以上の強度の署名であること。 ### サーバー証明書 [内部TLS](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/concepts#components)中にプロキシによって提示されます。 * 登録済みのCAによって直接署名されていること（中間証明書なし）。 * `AuthorityKeyIdentifier` 拡張が存在し、CAの `SubjectKeyIdentifier` と一致すること。 * Subject Alternative Nameに `.` に一致するDNS名が含まれること。ワイルドカード `*.` はすべてのルートをカバーします。 * `ExtendedKeyUsage` 拡張が存在する場合、`serverAuth` が含まれること。 * 有効期間内であること。 * RSA 2048ビット以上、またはECDSA P-256以上で、SHA-256以上の強度の署名であること。 セットアップコンポーネントは、有効期間5年のECDSA P-256 CAと、ワイルドカードSANを持つ有効期間90日のRSA 4096ビットサーバー証明書を生成します。 ## セットアップコンポーネント セットアップコンポーネントは、`mcp-proxy` イメージ内に `setup` バイナリとして同梱されています。`docker compose run --rm setup `（Compose）で実行するか、チャートのフックとCronJob（Helm）に任せます。 ### `setup init` 既存のトンネルにアタッチし（トンネルIDが指定されていない場合は作成し）、CAとサーバー証明書を生成し、CAを登録し、トンネルトークンを取得して、すべての出力を出力先に書き込みます。 | フラグ | 説明 | デフォルト | | ----------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | | `--api-url` | Claude APIのベースURL。`API_URL` からも読み込まれます。 | 必須 | | `--tunnel-id` | アタッチするトンネルID（`tnl_...`）。`TUNNEL_ID` からも読み込まれます。省略した場合、新しいトンネルが作成されます。出力にすでに保存されているトンネルIDは再実行時に再利用されます。 | なし（トンネルを作成） | | `--output` | 出力先：`dir:/path` または `k8s-secret:NAME`。Helmチャートは `k8s-secret:` を渡します。 | `k8s-secret:mcp-tunnel`（Kubernetesポッド内で実行している場合は自動検出、それ以外の場合は必須） | | `--cert-duration` | サーバー証明書の有効期間。 | `2160h`（90日） | | `--token-version` | 変更検出用の文字列。新しい値を指定すると、再実行時にトークンのローテーションがトリガーされます。HelmチャートとComposeの例はどちらも初期値として `1` を渡します。 | なし | このコマンドは[Workload Identity Federation](https://platform.claude.com/docs/ja/manage-claude/workload-identity-federation)を通じて認証します。`ANTHROPIC_FEDERATION_RULE_ID`、`ANTHROPIC_ORGANIZATION_ID`、`ANTHROPIC_WORKSPACE_ID`（オプション）、および `ANTHROPIC_IDENTITY_TOKEN_FILE` または `ANTHROPIC_IDENTITY_TOKEN` のいずれか一方のみを読み込みます。これらの変数の現在のセマンティクスについては、[WIFリファレンス](https://platform.claude.com/docs/ja/manage-claude/wif-reference)を参照してください。セットアップコンポーネントはフェデレーションルールからサービスアカウントを導出するため、`ANTHROPIC_SERVICE_ACCOUNT_ID` を別途必要としません。 ### `setup renew-cert` 保存されたCAによって署名された新しいサーバー証明書を発行します。API呼び出しは行いません。 | フラグ | 説明 | デフォルト | | ----------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `--output` | 出力先：`dir:/path` または `k8s-secret:NAME`。Helmチャートは `k8s-secret:` を渡します。 | `k8s-secret:mcp-tunnel`（Kubernetesポッド内で実行している場合は自動検出、それ以外の場合は必須） | | `--cert-duration` | 新しい証明書の有効期間。 | `2160h`（90日） | | `--renew-before` | 既存の証明書の残り有効期間がこの期間より長い場合、更新をスキップします。 | `0`（常に更新） | `--renew-before=720h` を設定すると、有効期間が30日より多く残っている場合にコマンドは何も行わないため、固定スケジュールで安全に実行できます。