MCP tunnelsリファレンス — プロキシ設定とTunnels APIの認証・証明書要件

MCP tunnelsのプロキシは何を設定するのか

MCP tunnelsは、プライベートネットワーク内で動くMCPサーバーへ、インバウンドポートを一切開けずにClaudeから到達させる仕組みです。実体は2つのコンテナです。Cloudflareのcloudflaredが外向き接続をトンネルエッジへ張ります。Anthropic側のプロキシ(コンテナ名mcp-proxy)は、その接続の中で内側TLSを終端し、アップストリームのMCPサーバーへ振り分けます。MCPそのものの仕組みはMCPとはで扱っているので、ここではトンネル固有の設定項目とAPIに絞ります。なおMCP tunnelsはResearch Preview段階の機能で、利用には申請が必要です。稼働率・サポート・継続性の保証は付かず、Anthropicはいつでも仕様変更や提供終了を行えるとしています。本記事のキー名や既定値も、その前提で読んでください。

プロキシはCompose環境では/etc/mcp-gateway/config.yaml、Helm環境ではConfigMap(gateway.config.*から描画)を読み込みます。主要フィールドは次のとおりです。

https://のアップストリームルートを使うなら、upstream.tls.ca_fileかupstream.tls.include_system_casの少なくとも一方を設定してください。どちらも無いと、プロキシはアップストリーム証明書を信頼する手がかりを持てません。

upstream.allowed_ipsの既定値はRFC1918のプライベートアドレス範囲です。アップストリームのMCPサーバーをVPCピアリングや専用線経由でこの範囲外のアドレス(パブリックIPを持つロードバランサーなど)に置いている場合は、既定のままでは接続がIP検証で弾かれます。該当するCIDRをallowed_ipsに明示的に追加するか、要件次第ではdisable_ip_validationで検証自体を無効化する必要があります。

ルートマッチングは連想配列であってリストではない

routesはmap[string]stringのフラットな連想配列です。YAMLでリスト形式(- name: url)で書くと、プロキシはcannot unmarshal !!seq into map[string]stringで起動に失敗します。マッチングはまず完全一致を試し、続いてtunnel_domainのサフィックスを除いたサブドメインで照合します。リクエストパスとクエリ文字列はそのままアップストリームへ転送され、ホスト名だけが振り分けの判断材料です。

アップストリームの値は必ずscheme://host:portの形式で、ポート番号の省略はできません。パスを含めると設定読み込み時点でinvalid upstream (must be scheme://host:port)として拒否されます。

Tunnels APIの認証とエンドポイント

Tunnels REST APIは/v1/tunnelsを起点に、トンネルの作成・一覧・アーカイブ、CA証明書の登録、トンネルトークンの参照とローテーションを扱います。以前の管理者向けAPI(/v1/organizations/tunnels、betaヘッダーmcp-tunnels-2026-05-19、スコープorg:manage_tunnels)は移行期間中は動き続けますが非推奨表示が付いています。

新旧のエンドポイントは次の3点で違います。

すべてのリクエストで必要なヘッダーは次の3つです。

curl https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $WIF_EXCHANGED_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-06-22"

MCPサーバー自体をstdio/HTTPで直接接続する通常の方法はAgent SDK MCP接続ガイドで扱っています。MCP tunnelsはそのうちHTTP接続の一種を、プライベートネットワーク越しに安全に成立させるための追加レイヤーだと捉えると位置づけが掴みやすくなります。

/v1/tunnels配下でできる操作は、トンネルの作成・一覧取得・アーカイブ、CA証明書の登録、トンネルトークンの参照とローテーションの5系統です。運用上よく使うのは2つです。CI/CDからトンネル一覧を取得して有効な証明書があるかを確認する用途と、ローテーションポリシーに沿ってトンネルトークンを定期的に入れ替える用途です。

資格情報の提供方式は2つある

トンネルスタックが実行時に必要とする資格情報は、cloudflaredの外向き接続を認証するトンネルトークンと、プロキシが内側TLSで提示するサーバー証明書の2つです。これをどう供給するかには2つの方式があります。

プログラマティック方式(推奨、Helmの既定はsetup.enabled: true)は、setupコンポーネントがWorkload Identity Federation経由でTunnels APIに認証し、トンネルトークンを取得し、CAとサーバー証明書をその場で生成して登録します。長期の秘密情報を手作業でコピーする必要はありません。workspace:manage_tunnelsスコープを持つフェデレーションルールがあれば成立します。

マニュアル方式(Helmのsetup.enabled: false)は、Console上でトンネルトークンをコピーし、CAとサーバー証明書を自分で(たとえばopensslで)発行し、ConsoleでCAを登録し、トークンと証明書をシークレットとしてスタックに渡します。setupコンポーネントは動きません。

どちらもドキュメント内では「プログラマティックフロー」「マニュアルフロー」と呼ばれ、後述のsetup initはプログラマティックフローだけが対象です。マニュアルフローを選ぶ理由は、OIDCの発行元(Kubernetesクラスタ、クラウドIAM、SPIFFEなど)を持たない場合や、動作検証だけが目的の場合です。

ネットワーク要件 — どこと何のポートで通信するか

ファイアウォールを設計する担当者が最初に見るべき表です。3つのコンポーネントは、それぞれ別の宛先とだけ通信できればよく、逆に言えばそれ以外への到達性は不要です。

インバウンドポートはどのコンポーネントにも存在しません。cloudflaredが張るのはあくまで外向きの接続です。その1本の接続の中を、リクエストが逆向き(Anthropicからあなたのネットワークへ)に流れます。これが一般的なMCP接続とは異なる、トンネル特有の構造です。

証明書要件 — CA証明書とサーバー証明書

setupコンポーネントを使えば証明書は自動生成されるため、以下の要件は自前のPKIで発行する場合(マニュアル方式)にだけ意識すれば足ります。

CA証明書はPOST /v1/tunnels/{tunnel_id}/certificatesで登録します。PEMエンコードで8kB以内、BasicConstraintsのCA:TRUEをcritical指定で持たせ、SubjectKeyIdentifier拡張とkeyCertSignを含むKeyUsageが必須です。鍵長はRSA 2048bit以上またはECDSA P-256以上、署名はSHA-256以上を使います。1つのトンネルは、無停止ローテーションのために最大2枚のCA証明書を同時に保持できます。

サーバー証明書は登録済みのCAから直接署名します。中間証明書は使えません。AuthorityKeyIdentifierがCAのSubjectKeyIdentifierと一致し、SANに<route>.<tunnel-domain>または*.<tunnel-domain>のワイルドカードを含む必要があります。setupコンポーネントが生成する既定値は、5年有効なECDSA P-256のCAと、90日有効・ワイルドカードSAN付きのRSA 4096bitサーバー証明書です。

CAの入れ替えは、有効期限が近づいた既存CAをそのまま残した状態で、もう一方の枠に新しいCAを登録し、以降発行するサーバー証明書だけを新CAの署名に切り替える順序で進めます。2枚を同時に保持できる間は、プロキシと接続先の双方が常にどちらか有効なCAを信頼できる状態を保てるため、切り替えの最中にトンネルが一時的に信頼されなくなる瞬間が生まれません。次回のローテーションでは今回登録した新CAが「据え置き側」になり、同じ手順をもう一方の枠に対して繰り返します。

初期化と証明書更新(init / renew-cert)

setupコンポーネントはmcp-proxyイメージに同梱されるsetupバイナリで、Composeならdocker compose run --rm setup <subcommand>、Helmならチャートのフックとして動きます。

setup initは既存のトンネルに接続する(トンネルIDを省略すると新規作成)、CAとサーバー証明書を生成する、CAを登録する、トンネルトークンを取得する、という一連の処理を1コマンドでこなします。

docker compose run --rm setup init \
  --api-url https://api.anthropic.com \
  --tunnel-id tnl_xxxxxxxx

--token-versionはHelmチャートとCompose例のどちらも初期値に1を渡しており、値を変えてsetup initを再実行するとトンネルトークンだけがローテーションします。証明書には手を付けずトークンだけを入れ替えたい場面、たとえばトークンの漏えいが疑われたときの緊急ローテーションや、定期的なトークン更新ポリシーに沿った運用に向いた使い方です。

setup renew-certはAPIを一切呼ばず、保存済みのCAで新しいサーバー証明書を発行するだけです。--renew-beforeに720h(30日)を指定しておくと、有効期限まで30日以上残っている間は何もしないため、cronで定期実行しても安全です。

MCP tunnelsのAPI移行は管理者専用機能から現場権限への移行

旧/v1/organizations/tunnelsは、組織全体に及ぶorg:manage_tunnelsスコープを要求していました。新しい/v1/tunnelsは、ワークスペース単位のworkspace:manage_tunnelsをWorkload Identity Federation経由の短命トークンで要求します。トンネル管理という強い権限を組織全体の管理者キーから切り離し、ワークスペースごとの一時的な認証へ寄せる動きです。管理者APIキーを恒久的に配布する運用から、認証基盤(IdP)が発行する短命トークンへ主導権を移す設計は、Claude Codeの他のエンタープライズ機能でも繰り返し採用されているパターンで、MCP tunnelsもその流れに合流したと見てよいでしょう。

実務への影響は明確です。ワークスペースをまたいで複数チームがトンネルを持つ組織では、旧APIのように組織全体のキー1つで全トンネルを操作できる状態から、ワークスペースごとにフェデレーションルールを分けて権限を分割できる状態に変わります。監査ログの側から見ても効果があります。「誰が」ではなく「どのワークスペースのどのサービスアカウントが」操作したかを追える粒度になる点は、移行の手間に見合うメリットだと言えます。

まとめ — 誰が今すぐ設定を確認すべきか

移行期間中のmcp-tunnels-2026-05-19ヘッダーをまだ使っているチームは、パスを/v1/tunnelsへ、ヘッダーをmcp-tunnels-2026-06-22へ、WIFトークンのスコープをworkspace:manage_tunnelsへ切り替える作業が必要です。これから新規に導入するなら、プログラマティック方式を選んでsetupコンポーネントに証明書管理を任せましょう。CA・サーバー証明書双方の要件を自分で満たす手間は発生しません。routesをリスト形式で書いてしまう設定ミスと、アップストリームURLにパスを含めてしまうミスの2つは、起動時のエラーメッセージが具体的なので原因の切り分けは難しくありません。ファイアウォール担当者は、setupコンポーネント・cloudflared・プロキシの3コンポーネントがそれぞれ別の宛先としか通信しない前提で許可リストを組めば、過不足のない設定になります。