メッセージMCPトンネル

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

トンネルスタックにおける接続性、TLS、IP検証、OAuthルーティングの問題を診断します。

MCPトンネルはリサーチプレビュー段階です。お試しいただくにはアクセスをリクエストしてください。

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

クイックリファレンス

症状	原因	修正方法
エージェントの + MCP Server ピッカーにトンネルが表示されない	ピッカーには、セッションのワークスペース内にあり、少なくとも1つのアクティブな証明書を持つトンネルのみが表示されます。	CA証明書を登録するか、トンネルが作成されたワークスペースでセッションを開いてください。
呼び出し元にHTTP 500が表示され、cloudflaredが`No ingress rules were defined`をログに記録する	cloudflaredにローカルターゲットがありません。	cloudflaredサービスに`--url http://localhost:8080`と`network_mode: "service:mcp-proxy"`を追加してください。
プロキシが`no route for host`をログに記録する	`tunnel_domain`が割り当てられたドメインと一致していないか、プロキシを再起動せずに`config.yaml`が編集されました。	トンネル詳細ページに表示されている正確なドメインを`tunnel_domain`に設定し、プロキシを再起動してください（`docker compose restart mcp-proxy`）。
プロキシが`IP validation failed: <ip> is not a private address`をログに記録する	アップストリームMCPサーバーがRFC1918の範囲外に解決されています。	アップストリームIP検証を参照してください。
プロキシが`cannot unmarshal !!seq into map[string]string`で終了する	`routes`がYAMLリストになっています。	`routes: { name: http://host:port }`を使用してください。
プロキシが`open /data/tls.key: permission denied`で終了する	キーが`0600`で、プロキシコンテナが非rootで実行されています。	`chmod 644 data/tls.key`を実行してください。
`curl https://<proxy>:8080`が`wrong version number`で失敗する	これは想定内です。リスナーはプレーンテキストWebSocketです。TLSはWSストリーム内で行われます。	代わりにManaged AgentまたはMessages APIを通じて検証してください。

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

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

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

認可サーバー用のプロキシルートを追加する
routes: mcp: http://your-mcp-server:8080 auth: http://your-auth-server:8080
routesを編集した後、プロキシを再起動してください（docker compose restart mcp-proxy、またはhelm upgrade）。
分割エンドポイントのディスカバリーメタデータを提供する
認可サーバーの/.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"] }
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、lifetime）は同じです。

トンネル固有の原因：

チャートのデフォルトaudienceはapi.anthropic.com（スキームなし）です。ルールのaudienceがhttps://api.anthropic.comの場合は、api.wif.audienceを一致するように設定してください。
交換が成功した後にTunnels APIから403が返される場合、ルールのスコープにorg: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からエッジへのegress範囲は別のホップです。）

プロキシが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サーバーが使用するプライベート範囲も含めてください：

config/mcp-proxy.yaml

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

ローカルテスト以外では0.0.0.0/0の使用を避けてください。SSRF保護が完全に無効になります。

Was this page helpful?

メッセージMCPトンネル

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

トンネルスタックにおける接続性、TLS、IP検証、OAuthルーティングの問題を診断します。

MCPトンネルはリサーチプレビュー段階です。お試しいただくにはアクセスをリクエストしてください。

クイックリファレンス

症状	原因	修正方法
エージェントの + MCP Server ピッカーにトンネルが表示されない	ピッカーには、セッションのワークスペース内にあり、少なくとも1つのアクティブな証明書を持つトンネルのみが表示されます。	CA証明書を登録するか、トンネルが作成されたワークスペースでセッションを開いてください。
呼び出し元にHTTP 500が表示され、cloudflaredが`No ingress rules were defined`をログに記録する	cloudflaredにローカルターゲットがありません。	cloudflaredサービスに`--url http://localhost:8080`と`network_mode: "service:mcp-proxy"`を追加してください。
プロキシが`no route for host`をログに記録する	`tunnel_domain`が割り当てられたドメインと一致していないか、プロキシを再起動せずに`config.yaml`が編集されました。	トンネル詳細ページに表示されている正確なドメインを`tunnel_domain`に設定し、プロキシを再起動してください（`docker compose restart mcp-proxy`）。
プロキシが`IP validation failed: <ip> is not a private address`をログに記録する	アップストリームMCPサーバーがRFC1918の範囲外に解決されています。	アップストリームIP検証を参照してください。
プロキシが`cannot unmarshal !!seq into map[string]string`で終了する	`routes`がYAMLリストになっています。	`routes: { name: http://host:port }`を使用してください。
プロキシが`open /data/tls.key: permission denied`で終了する	キーが`0600`で、プロキシコンテナが非rootで実行されています。	`chmod 644 data/tls.key`を実行してください。
`curl https://<proxy>:8080`が`wrong version number`で失敗する	これは想定内です。リスナーはプレーンテキストWebSocketです。TLSはWSストリーム内で行われます。	代わりにManaged AgentまたはMessages APIを通じて検証してください。

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

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

認可サーバー用のプロキシルートを追加する
routes: mcp: http://your-mcp-server:8080 auth: http://your-auth-server:8080
routesを編集した後、プロキシを再起動してください（docker compose restart mcp-proxy、またはhelm upgrade）。
分割エンドポイントのディスカバリーメタデータを提供する
認可サーバーの/.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"] }
MCPサーバーをトンネルのissuerに向ける
MCPサーバーの/.well-known/oauth-protected-resourceレスポンスでは、認可サーバーとしてトンネルのホスト名を参照する必要があります：
{ "resource": "https://mcp.<tunnel-domain>", "authorization_servers": ["https://auth.<tunnel-domain>"] }

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

トンネル固有の原因：

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

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

トンネルが接続しない

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

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

証明書エラー

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

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

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

アップストリームIP検証

config/mcp-proxy.yaml

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

ローカルテスト以外では0.0.0.0/0の使用を避けてください。SSRF保護が完全に無効になります。

Was this page helpful?