MCPトンネルのトラブルシューティング

トンネルを経由するリクエストは、3つのレイヤーのいずれかで失敗する可能性があります。順番に診断してください。まずトンネルエッジへのアウトバウンド接続、次にAnthropicからプロキシへの内部TLS、そしてアップストリームMCPサーバーへのルーティングとIP検証です。

クイックリファレンス

以下のセクションでは、1行の修正では解決できない障害について説明します。

送信元IP許可リストの背後でOAuthが失敗する

認可サーバーの送信元IP許可リストが、Anthropicのバックエンドから /token、/register、およびディスカバリーエンドポイントへのアクセスをブロックしている場合、OAuthフローは失敗します。Anthropicのエグレス範囲を許可リストに追加したくない場合は、ブラウザ向けの /authorize エンドポイントを既存のパブリックホスト名に残したまま、バックエンド間のOAuth呼び出しをトンネル経由でルーティングできます。

1. 1

   認可サーバー用のプロキシルートを追加する

   routes:
     mcp: http://your-mcp-server:8080
     auth: http://your-auth-server:8080

   

   routes を編集した後はプロキシを再起動してください（docker compose restart mcp-proxy、または helm upgrade）。

2. 2

   エンドポイントを分割したディスカバリーメタデータを提供する

   認可サーバーの /.well-known/oauth-authorization-server レスポンスでは、authorization_endpoint を既存の許可リスト登録済みホスト名に向け、それ以外はすべてトンネルに向ける必要があります。

   {
     "issuer": "https://auth.<tunnel-domain>",
     "authorization_endpoint": "https://<your-allowlisted-host>/authorize",
     "token_endpoint": "https://auth.<tunnel-domain>/token",
     "registration_endpoint": "https://auth.<tunnel-domain>/register",
     "code_challenge_methods_supported": ["S256"]
   }

   
3. 3

   MCPサーバーをトンネルのissuerに向ける

   MCPサーバーの /.well-known/oauth-protected-resource レスポンスでは、認可サーバーとしてトンネルのホスト名を参照する必要があります。

   {
     "resource": "https://mcp.<tunnel-domain>",
     "authorization_servers": ["https://auth.<tunnel-domain>"]
   }

   

この構成では、ユーザーのブラウザは既存のホスト名の /authorize にアクセスし（これは許可リストですでに許可されています）、Anthropicのバックエンドは /token、/register、およびディスカバリードキュメントにトンネル経由でアクセスします。

セットアップコンポーネントの認証失敗

セットアップコンポーネント（Helm JobまたはComposeの setup サービス）は、フェデレーションルールを通じてOIDC JWTを交換することでTunnels APIに対して認証します。交換が失敗した場合は、Workload Identity Federationリファレンスの失敗した交換のトラブルシューティングを参照してください。失敗モード（subject、audience、issuer、JWKS、有効期間）は同じです。

トンネル固有の原因：

• チャートのデフォルトのaudienceは api.anthropic.com（スキームなし）です。ルールのaudienceが https://api.anthropic.com の場合は、api.wif.audience を一致するように設定してください。
• 交換が成功した後にTunnels APIから 403 が返される場合、ルールのスコープに workspace:manage_tunnels が含まれていないか、ルールのサービスアカウントがトンネルのワークスペースのメンバーではありません。スコープを設定し、サービスアカウントをワークスペースに追加してください。

Helmでは、セットアップコンポーネントはpre-installフックのJobとして実行されます。失敗した場合、Jobは調査のために残されます（kubectl logs job/mcp-tunnel-setup -n mcp-tunnel）。Helmはフックリソースを管理しないため、再試行する前に削除してください。

helm uninstall mcp-tunnel -n mcp-tunnel
kubectl -n mcp-tunnel delete job mcp-tunnel-setup

トンネルが接続しない

まずcloudflaredのログを確認してください。一般的な原因：

• TUNNEL_TOKEN が欠落している、期限切れである、または正しくコピーされていない。
• ファイアウォールがトンネルエッジへのポート7844のアウトバウンドTCP/UDPをブロックしている。

cloudflaredはUDP受信バッファサイズに関する警告をログに記録することもあります。これはQUICのチューニングに関するヒントであり、エラーではありません。

証明書エラー

内部TLS中にAnthropicがプロキシの証明書を拒否すると、プロキシは tls handshake failed をログに記録します。以下を確認してください。

• サーバー証明書の有効期限が切れていないこと。
• 証明書のSubject Alternative Nameが *.<tunnel-domain> と一致していること。
• 署名したCAがこのトンネル用にAnthropicに登録されていること。

完全な検証ルールについては、証明書の要件を参照してください。

アップストリームIP検証

SSRF保護のため、プロキシはデフォルトでRFC1918のプライベート範囲（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）内のアドレスにのみ接続します。プロキシからアップストリームへの接続ではIPv4のみがサポートされています。（ネットワーク要件に記載されているcloudflaredからエッジへのエグレス範囲は別のホップです。）

プロキシのログに IP validation failed: <ip> is not a private address と記録される場合、アップストリームのホスト名がその範囲外に解決されています。Kubernetesでは、一部のマネージドディストリビューションがService CIDRをRFC1918の範囲外に割り当てます。kubectl get svc kubernetes -n default -o jsonpath='{.spec.clusterIP}' がプライベート範囲外のアドレスを返す場合は、クラスターのService CIDRを調べて追加してください。

アドレスが正当なものである場合は、それをカバーする最も狭いCIDRを upstream.allowed_ips に追加してください。allowed_ips を設定すると、RFC1918のデフォルトを拡張するのではなく置き換えるため、他のアップストリームMCPサーバーが使用するプライベート範囲も含めてください。

upstream:
  allowed_ips:
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
    - 127.0.0.0/8       # loopback, for local testing only