本指南針對您在開發模型內容通訊協定 (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 檔案 或 - 在屬性中
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 聊天觸發的工具
- 重新審視您的工具和參數描述,以確保它們提供足夠的上下文。 請考慮使用「使用此函數/參數時機...」來重寫它們措辭。
- 描述長度保持在 1,024 個字元以內。 超過 1,024 個字元的文字會被忽略。
- 確保工具可見性已正確設定。
- 對於 MCP 應用程式,
_meta.ui.visibility包含model。 - 對於 OpenAI SDK 應用程式,
meta["openai/visibility"]設定為public。
- 對於 MCP 應用程式,
選取了錯誤的工具
- 避免使用名稱相似或描述重疊的工具。
- 在描述中添加明確的區別符,解釋何時應使用每種工具。
小工具問題
小工具無法轉譯
如果呼叫了正確的 MCP 工具,但您的 UI 小工具未在回應中轉譯,則您的 MCP 伺服器可能只會傳回沒有 UI 元件的結構化內容。 確定已正確設定 UI 繫結。
- 對於 MCP 應用程式,工具定義包括
_meta.ui.resourceUri設定為具有 MIME 類型的text/html;profile=mcp-app已註冊 HTML 資源。 - 對於 OpenAI SDK 應用程式,工具定義包括
_meta["openai/outputTemplate"]設定為具有 MIME 類型的text/html+skybridge已註冊 HTML 資源。
無法載入小工具
- 開啟瀏覽器的開發人員工具,並在主控台中檢查內容安全性原則 (CSP) 違規。 確保來自小工具主機 URL 的要求已列為允許清單。 如需詳細資訊,請參閱 MCP 應用程式的 MCP 伺服器需求。
- 確認您的小工具會將所有 HTML 和 JavaScript 相依性編譯成單一檔案,且沒有外部未解析的資產。
載入小工具時沒有資料
- 驗證工具的回應結構。
-
content應該只包含資料 (模型) 。 -
structuredContent應該同時包含資料和小工具。 -
_meta應該只包含小工具。
-
- 確保
structuredContent或_meta包含必要的資料。
小工具有雙捲軸
Copilot 主機容器已有高度上限的捲軸。 透過在容器樣式中設定 overflow: hidden 來停用小工具中的內捲動。
未開啟小工具中的超連結
錨點標籤 <a> 不適用於 Copilot 中的外部連結。 請改為使用適當的平台 API。
- 針對 MCP 應用程式,請使用
app.openLink。 - 針對 OpenAI SDK 應用程式,請使用
window.openai.openExternal。
全螢幕在某些 Copilot 主機中無法運作
並非所有 Copilot 主機都支援全螢幕檢視。 最佳做法是一律檢查主機功能,並有條件地顯示 UI 元素 (,例如全螢幕按鈕) 。 如需詳細資訊,請參閱 驗證 API 可用性。
回應問題
工具結果到期問題
確定工具回應已傳送contentstructuredContent或不會太大。 如果您的小工具需要對模型沒有用處的豐富中繼資料,例如頭像 URL 或 UI 特定詳細資料,請在 中 _meta 包含完整資料,並在 中 content提供簡潔摘要。 此方法可確保模型保留關鍵資訊,同時支援有效的多輪次體驗。
小工具和文字摘要中有重複資料
使用下列其中一個選項來解決此問題:
-
最佳化資料分離: 用於
_meta小工具特定資料和content模型可見摘要。 - 引導格式設定: 使用宣告式代理程式資訊清單中的指示來引導回應的結構和呈現方式。
驗證問題
針對驗證問題,例如登入失敗、權杖錯誤、同意提示和驗證設定不符,請參閱針對 MCP 和 API 外掛程式驗證進行疑難排解。