如何判斷問題所在
當元件無法呈現、探索功能未能對提示詞做出預期回應，或身分驗證陷入循環時，請先找出問題出在哪一層：伺服器、元件，還是 ChatGPT 用戶端。以下檢查清單涵蓋最常見的問題及其解決方式。
伺服器、工具與探索功能的檢查適用於 ChatGPT 和 Codex 中的外掛程式。本頁的使用者介面、小工具狀態與用戶端身分驗證檢查則說明 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 錯誤： 在錯誤回應中加入
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 會重複使用這些憑證，因此請還原原有憑證，而非建立新的用戶端。存取 Token 過期則需要採取不同的修正方式。
部署問題
- ngrok 通道逾時： 重新啟動通道，並在分享 URL 前確認本機伺服器正在執行。正式環境請使用穩定且提供健康檢查的託管服務供應商。
- 透過 Proxy 時串流中斷： 確認負載平衡器或 CDN 允許伺服器傳送事件或串流 HTTP 回應通過，且不會進行緩衝。
何時尋求進一步協助
如果你已確認上述各項，但問題仍然存在：
- 收集記錄（伺服器記錄、元件主控台記錄、ChatGPT 工具呼叫逐字記錄）與螢幕截圖。
- 記下你送出的提示詞與任何確認訊息。
- 將詳細資訊提供給你的 OpenAI 合作夥伴聯絡人，讓對方能在內部重現問題。
清楚精簡的疑難排解記錄能縮短處理時間，讓你的 MCP 伺服器持續為使用者提供可靠的服務。