問題の切り分け方法
コンポーネントが表示されない、プロンプトに対応するツールが検出されない、認証がループするといった問題が発生したら、まずサーバー、コンポーネント、ChatGPT クライアントのどの層に原因があるかを切り分けます。以下のチェックリストでは、よくある問題とその解決方法を説明します。
サーバー、ツール、検出に関する確認事項は、ChatGPT と Codex のプラグインに適用されます。このページの UI、ウィジェットの状態、クライアント認証に関する確認事項は、ChatGPT の動作について説明しています。
サーバー側の問題
- ツールが一覧に表示されない： サーバーが稼働していて、
/mcpエンドポイントに接続していることを確認します。ポートを変更した場合は、MCP サーバーの URL を更新し、MCP Inspector を再起動します。 - 構造化コンテンツのみで、コンポーネントが表示されない： ツール記述子の
_meta.ui.resourceUriが、mimeType: "text/html;profile=mcp-app"を指定した登録済みの HTML リソースを指していることを確認します（ChatGPT では、互換性のための任意のエイリアスとして_meta["openai/outputTemplate"]も使用できます）。また、リソースが CSP エラーなしで読み込まれることを確認します。 - スキーマ不一致エラー： Python または TypeScript のモデルが、
outputSchemaで公開しているスキーマと一致していることを確認します。変更後は型を再生成します。 - 応答が遅い： ツール呼び出しに数百ミリ秒以上かかると、コンポーネントの動作が遅く感じられます。サーバー呼び出しをプロファイリングし、可能な場合は結果をキャッシュします。
ウィジェットの問題
- ウィジェットが読み込まれない： ブラウザのコンソール（または MCP Inspector のログ）を開き、CSP 違反やバンドルの欠落がないか確認します。HTML にコンパイル済みの JavaScript が含まれ、バンドルにすべての依存関係が含まれていることを確認します。
- ドラッグ＆ドロップや編集の結果が保持されない： ChatGPT によるウィジェットの状態の永続化を利用している場合は、更新のたびに
window.openai.setWidgetStateを呼び出し、マウント時にwindow.openai.widgetStateから状態を復元します。 - モバイルでのレイアウトの問題： ChatGPT が提供するレイアウト情報を利用している場合は、
window.openai.displayModeとwindow.openai.maxHeightを確認してレイアウトを調整します。固定の高さや、ホバーでしか実行できない操作は避けます。
検出とエントリーポイントの問題
- ツールがまったく呼び出されない： メタデータを見直します。「…の場合に使用します」という表現で説明を書き直し、開始用プロンプトを更新して、基準となるプロンプトセットで再テストします。
- 誤ったツールが選択される： 似たツールの違いが明確になるよう説明を補足するか、使用してはいけない状況を説明に明記します。大きなツールを、特定の目的に特化した小さなツールに分割することも検討します。
- ランチャーの表示順位が適切でない： ディレクトリのメタデータを更新し、プラグインのアイコンと説明がユーザーの期待に合っていることを確認します。
認証の問題
- 401 エラー： ChatGPT が OAuth フローを再開する必要があると判断できるよう、エラーレスポンスに
WWW-Authenticateヘッダーを含めます。発行者の URL とオーディエンスクレームも再確認します。 - クライアントの登録に失敗する： CIMD を使用している場合は、認可サーバーのメタデータに
client_id_metadata_document_supported: trueが含まれていることと、認可サーバーが ChatGPT のクライアントメタデータドキュメントを取得できることを確認します。private_key_jwtを使用している場合は、認可サーバーが ChatGPT の公開 JWKS を取得し、署名済みクライアントアサーションを検証できることを確認します。DCR を使用している場合は、認可サーバーがregistration_endpointを公開していることと、新しく作成したクライアントで少なくとも 1 つのログイン接続が有効になっていることを確認します。 - 既存の MCP サーバー接続が
invalid_clientを返す： 動的に登録された OAuth クライアントが引き続き存在し、クライアントシークレットがある場合は認可サーバーがそれを受け付けることを確認します。ChatGPT はこれらの認証情報を再利用するため、新しいクライアントを作成するのではなく、元の認証情報を復元します。アクセストークンの有効期限切れには、別の対処が必要です。
デプロイの問題
- ngrok トンネルがタイムアウトする： トンネルを再起動し、ローカルサーバーが稼働していることを確認してから URL を共有します。本番環境では、ヘルスチェックを備えた安定したホスティングプロバイダーを使用します。
- プロキシ経由でストリーミングが機能しない： ロードバランサーや CDN が、サーバー送信イベントまたはストリーミング HTTP レスポンスをバッファリングせずに通過させる設定になっていることを確認します。
エスカレーションのタイミング
上記の項目を確認しても問題が解決しない場合は、次の手順を実施します。
- ログ（サーバー、コンポーネントのコンソール、ChatGPT のツール呼び出し記録）とスクリーンショットを収集します。
- 入力したプロンプトと、表示された確認メッセージを記録します。
- OpenAI のパートナー担当者に詳細を共有し、社内で問題を再現できるようにします。
要点を押さえたトラブルシューティングの記録は、対応時間の短縮につながり、ユーザーが安心して使える MCP サーバーの維持に役立ちます。