MCPトンネルリファレンス



プロキシ設定

プロキシは、/etc/mcp-gateway/config.yaml（Compose）またはレンダリングされたConfigMap（Helm、gateway.config.*から値が設定される）から設定を読み込みます。

https://アップストリームルートの場合、upstream.tls.ca_fileまたはupstream.tls.include_system_casの少なくとも一方を設定してください。そうしないと、プロキシはアップストリーム証明書のトラストアンカーを持ちません。



ルートマッチング

routesはリストではなく、フラットな文字列マップ（map[string]string）です。プロキシは、まず受信ホスト名を完全一致で検索し、次にtunnel_domainサフィックスを削除して残りのサブドメインでマッチングします。マッチングはホスト名のみを考慮し、リクエストパスとクエリ文字列は変更されずにアップストリームMCPサーバーに転送されます。

各アップストリーム値は正確にscheme://host:portである必要があります。ポートは必須です。パスを含めると、設定読み込み時にinvalid upstream (must be scheme://host:port)として拒否されます。



Tunnels API

Tunnels REST APIは/v1/tunnelsに配置されており、トンネルの作成、一覧表示、アーカイブ、CA証明書の登録、トンネルトークンの表示またはローテーションをサポートしています。すべてのエンドポイント、リクエストおよびレスポンススキーマ、例については、Tunnels APIリファレンスを参照してください。

すべてのリクエストに必要なヘッダー：



証明書要件

セットアップコンポーネントは、準拠した証明書を自動的に生成します。これらの要件は、独自のPKIを通じて証明書を発行する場合にのみ適用されます。



CA証明書

POST /v1/tunnels/{tunnel_id}/certificatesでアップロードします。トンネルは一度に最大2つのアクティブなCA証明書を保持でき、これによりダウンタイムなしのローテーションが可能になります。

• PEMエンコードされた単一の証明書で、最大8 kB。
• BasicConstraints拡張が存在し、CA:TRUEでクリティカルとしてマークされている。
• SubjectKeyIdentifier拡張が存在する。
• KeyUsageにkeyCertSignが含まれている。
• 有効期間内である。
• RSA 2048ビット以上、またはECDSA P-256以上で、SHA-256以上の署名を持つ。



サーバー証明書

内部TLS中にプロキシによって提示されます。

• 登録されたCAによって直接署名されている（中間証明書なし）。
• AuthorityKeyIdentifier拡張が存在し、CAのSubjectKeyIdentifierと一致している。
• Subject Alternative Nameに<route>.<tunnel-domain>と一致するDNS名が含まれている。ワイルドカード*.<tunnel-domain>はすべてのルートをカバーします。
• 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 <subcommand>で実行するか（Compose）、チャートのフックとCronJobに依存します（Helm）。



setup init

既存のトンネルにアタッチし（トンネルIDが指定されていない場合は新規作成し）、CAとサーバー証明書を生成し、CAを登録し、トンネルトークンを取得し、すべての出力を出力先に書き込みます。

このコマンドはWorkload Identity Federationを通じて認証します。ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_WORKSPACE_ID（オプション）、およびANTHROPIC_IDENTITY_TOKEN_FILEまたはANTHROPIC_IDENTITY_TOKENのいずれか一方を読み込みます。これらの変数の現在のセマンティクスについては、WIFリファレンスを参照してください。セットアップコンポーネントはフェデレーションルールからサービスアカウントを導出するため、ANTHROPIC_SERVICE_ACCOUNT_IDを別途必要としません。



setup renew-cert

保存されたCAによって署名された新しいサーバー証明書を発行します。API呼び出しは行いません。

--renew-before=720hを設定すると、有効期間が30日以上残っている場合にコマンドが何もしなくなるため、固定スケジュールで安全に実行できます。