如何找出問題所在
如果元件無法顯示、探索功能找不到提示詞,或身分驗證流程不斷重複,請先判斷問題出在哪一層:伺服器、元件或 ChatGPT 用戶端。以下檢查清單列出最常見的問題及其解決方法。
伺服器、工具和探索功能的檢查步驟適用於 ChatGPT 和 Codex 中的外掛程式。本頁關於使用者介面、小工具狀態和用戶端身分驗證的檢查步驟,則適用於 ChatGPT。
伺服器端問題
- 工具清單是空的: 確認伺服器正在執行,且你連線到的是
/mcp端點。如果變更了連接埠,請更新 MCP 伺服器的 URL,然後重新啟動 MCP Inspector。 - 只有結構化內容,沒有元件: 確認工具描述元中的
_meta.ui.resourceUri指向已註冊的 HTML 資源,且該資源設有mimeType: "text/html;profile=mcp-app"(為相容起見,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 錯誤: 在錯誤回應中加入
WWW-Authenticate標頭,讓 ChatGPT 知道需要重新啟動 OAuth 流程。再次核對簽發者 URL 和對象宣告。 - 用戶端註冊失敗: 如果使用 CIMD,請確認授權伺服器的中繼資料包含
client_id_metadata_document_supported: true,且伺服器能擷取 ChatGPT 的用戶端中繼資料文件。如果使用private_key_jwt,請確認授權伺服器能擷取 ChatGPT 的公開 JWKS,並驗證已簽署的用戶端斷言。如果使用 DCR,請確認授權伺服器提供registration_endpoint,且新建立的用戶端至少啟用了一個登入連線。 - 現有的 MCP 伺服器連線傳回
invalid_client: 確認動態註冊的 OAuth 用戶端仍然存在。如果該用戶端有用戶端密鑰,請確認授權伺服器仍接受該密鑰。ChatGPT 會重複使用這些憑證,因此請還原原有憑證,無須建立新的用戶端。存取權杖過期則需要採取不同的處理方式。
部署問題
- ngrok 通道逾時: 重新啟動通道,並在分享 URL 前確認本機伺服器正在執行。在正式環境中,請使用穩定且提供健康狀態檢查的代管服務。
- 透過 Proxy 時串流中斷: 確認負載平衡器或 CDN 允許伺服器傳送事件或串流 HTTP 回應直接通過,不會先緩衝這些資料。
何時尋求支援
如果已逐項完成上述檢查,問題仍然存在:
- 收集伺服器記錄、元件主控台記錄、ChatGPT 工具呼叫的完整紀錄,以及螢幕截圖。
- 記下你送出的提示詞和出現的任何確認訊息。
- 將這些詳細資料提供給你的 OpenAI 合作夥伴聯絡人,以便對方在內部重現問題。
簡明的疑難排解記錄能縮短問題處理時間,讓 MCP 伺服器持續為使用者提供可靠的服務。