如何排查问题
出现组件无法渲染、发现机制未能识别提示、身份验证反复循环等问题时，请先确定问题出在哪一层：服务器、组件还是 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 违规或缺失的打包文件。确保 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 前确认本地服务器正在运行。对于生产环境，请使用稳定且支持健康检查的托管服务提供商。
- 经过代理后流式传输中断： 确保您的负载均衡器或 CDN 允许服务器发送事件或流式 HTTP 响应通过，且不对其进行缓冲。
何时升级处理
如果您已检查以上各项，但问题仍然存在：
- 收集日志（服务器日志、组件控制台日志、ChatGPT 工具调用记录）和截图。
- 记录您发送的提示以及所有确认消息。
- 将详细信息分享给您在 OpenAI 的合作对接人，以便他们在内部复现问题。
清晰简明的故障排查记录有助于缩短处理时间，并确保您的 MCP 服务器为用户提供可靠的服务。