問題の切り分け方
コンポーネントが表示されない、ツールの検出時にプロンプトが見つからない、認証が繰り返されるといった問題が発生したら、まずサーバー、コンポーネント、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 違反やバンドルの欠落がないかを確認します。コンパイル済みの JavaScript が HTML に含まれ、必要な依存関係がすべてバンドルに含まれていることも確認します。
- ドラッグ＆ドロップや編集の結果が保存されない： 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 社内で問題を再現できるよう、これらの詳細を OpenAI のパートナー担当者と共有します。
調査内容を簡潔に記録しておくと、解決までの時間を短縮でき、ユーザーが MCP サーバーを安定して利用できます。