このガイドでは、モデル コンテキスト プロトコル (MCP) アプリを開発して Microsoft 365 Copilot 内の宣言型エージェントと統合するときに発生する可能性のある一般的な問題のトラブルシューティング アドバイスを提供します。
開発者モードを有効にする
開発者モードを有効にすると 、エージェントの応答にログとエラーが表示されます。 この情報は、デバッグに不可欠です。 開発者モードを有効にするには、Microsoft Copilot で次のコマンドを入力します。
-developer on
エージェントで使用できる MCP ツールは、デバッグ情報カードの [アクション] セクションに表示されます。 デバッグ情報カードの詳細については、「Microsoft 365 Copilot の開発者モードを使用してエージェントをテストおよびデバッグする」を参照してください。
検出とエントリの問題
ツールが一覧にありません
デバッグ情報カードの [アクション] セクションに MCP ツールが表示されない場合は、次の項目をチェックします。
- MCP サーバーが実行中であり、プラグイン マニフェスト内の正しい MCP エンドポイントに接続していることを確認します。
- 認証が成功したことを確認します。 多くの MCP サーバーは、ユーザーがサインインするまでツールを返さないため、サインインに失敗またはスキップすると、ツール リストが空になる可能性があります。
動的ツール検出
エージェントが 動的ツール検出 (既定) を使用している場合、ツールは実行時にサーバーから解決されます。 次の内容を確認する:
-
RemoteMCPServerランタイムはrun_for_functionsを["*"]に設定し、最上位のfunctions配列は空です。 - サーバーの
tools/listメソッドはツールを返します。 MCP インスペクターなどのツールを使用して応答を調べることができます。 - 新しく検出または変更されたツールは、ランタイム検証によって保留されません。 デバッグ情報で検証エラーを確認します。
"runtimes": [
{
"type": "RemoteMCPServer",
"spec": {
"url": "https://api.contoso.com/mcp"
},
"run_for_functions": [
"*"
]
}
]
ピン留めされたツール
固定のツール セットをピン留めした場合は、プラグイン マニフェストの runtimes プロパティで MCP サーバー ランタイムが指定されていることを確認します。
- 最上位の
functionsプロパティに必要なツールが含まれます。 - 次のいずれかの方法で
mcp_tool_descriptionプロパティ内のツールを参照します。-
fileプロパティでツールの説明を含む JSON ファイルを参照する OR -
toolsプロパティにツールの説明をインラインで一覧表示する
-
-
run_for_functionsプロパティにツール名を含めます。
"runtimes": [
{
"type": "RemoteMCPServer",
"spec": {
"url": "https://api.contoso.com/mcp",
"mcp_tool_description": {
"file": "mcp-tools.json"
}
},
"run_for_functions": [
"get_widget",
"create_widget"
]
}
]
Copilot Chat からトリガーされないツール
- ツールとパラメーターの説明を再確認して、十分なコンテキストを提供していることを確認します。 "この関数/パラメーターを使用する場合は..." と書き換えることを検討してください。言い回し。
- 説明文は 1,024 文字未満にしてください。 1,024 文字を超えるテキストは無視されます。
- ツールの可視性が正しく設定されていることを確認してください。
- MCP アプリの場合、
_meta.ui.visibilityにはmodelが含まれます。 - OpenAI SDK アプリの場合、
meta["openai/visibility"]はpublicに設定されます。
- MCP アプリの場合、
正しくないツールが選択されている
- 似たような名前や重複する説明のツールは避けてください。
- 各ツールを使用するタイミングを説明する説明に明確な差別化要因を追加します。
ウィジェットの問題
ウィジェットがレンダリングされない
正しい MCP ツールが呼び出されても、UI ウィジェットが応答でレンダリングされない場合、MCP サーバーは UI コンポーネントを含まない構造化されたコンテンツのみを返している可能性があります。 UI バインドが正しく構成されていることを確認してください。
- MCP アプリの場合、ツール定義には、MIME タイプ
text/html;profile=mcp-appを持つ登録済み HTML リソースに設定された_meta.ui.resourceUriが含まれます。 - OpenAI SDK アプリの場合、ツール定義には、MIME の種類が
text/html+skybridgeの登録済み HTML リソースに設定された_meta["openai/outputTemplate"]が含まれます。
ウィジェットの読み込みに失敗する
- ブラウザーの開発者ツールを開き、コンソールでコンテンツ セキュリティ ポリシー (CSP) 違反をチェックします。 ウィジェットのホスト URL からの要求が許可リストに登録されていることを確認します。 詳細については、「 MCP アプリの MCP サーバー要件」を参照してください。
- ウィジェットがすべての HTML と JavaScript の依存関係を、外部の未解決アセットなしで 1 つのファイルにコンパイルすることを確認します。
ウィジェットがデータなしで読み込まれる
- ツールの応答構造を確認します。
-
contentデータ (モデル) のみを含める必要があります。 -
structuredContentデータとウィジェットの両方が含まれている必要があります。 -
_metaウィジェットのみを含める必要があります。
-
-
structuredContentまたは_metaに必要なデータが含まれていることを確認します。
ウィジェットには二重スクロール バーがあります
Copilot ホスト コンテナーには、高さが最大になるスクロールが既にあります。 コンテナー スタイルで overflow: hidden を設定して、ウィジェットの内側スクロールを無効にします。
ウィジェット内のハイパーリンクが開かない
アンカー タグ <a> Copilot の外部リンクでは機能しません。 代わりに適切なプラットフォーム API を使用してください。
- MCP アプリの場合は、
app.openLinkを使用します。 - OpenAI SDK アプリの場合は、
window.openai.openExternalを使用します。
一部の Copilot ホストでは全画面表示が機能しない
全画面表示は、すべての Copilot ホストでサポートされているわけではありません。 ベスト プラクティスとして、ホスト機能を常にチェックし、条件付きで UI 要素 (全画面表示ボタンなど) を表示します。 詳細については、「 API の可用性の確認」を参照してください。
応答の問題
ツール結果の有効期限の問題
content または structuredContent を介して送信されるツール応答が大きすぎないようにします。 ウィジェットに、アバター URL や UI 固有の詳細など、モデルに役に立たないリッチなメタデータが必要な場合は、 _meta に完全なデータを含め、簡潔な要約を contentで提供します。 このアプローチにより、モデルは、効果的なマルチターン エクスペリエンスをサポートしながら、重要な情報を保持できます。
ウィジェットとテキスト要約の重複データ
次のいずれかの方法を使用して、この問題を解決します。
-
データの分離を最適化する: ウィジェット固有のデータには
_metaを使用し、モデルに表示されるサマリーにはcontentを使用します。 - 書式設定を制御する: 宣言型エージェント マニフェストの指示を使用して、応答の構造化と表示方法をガイドします。
認証の問題
サインインの失敗、トークン エラー、同意プロンプト、認証構成の不一致などの認証の問題については、「 MCP および API プラグイン認証のトラブルシューティング」を参照してください。