如何定位问题
如果组件无法渲染、发现过程中找不到提示词,或身份验证陷入循环,请先确定问题出在服务器、组件还是 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 前确认本地服务器正在运行。在生产环境中,请选择服务稳定且提供健康检查的托管服务商。
- 经过代理时流式传输中断: 确保负载均衡器或 CDN 允许传输服务器发送事件或流式 HTTP 响应,并且不会缓冲这些内容。
何时寻求进一步支持
如果您已逐项核对上述内容,但问题仍然存在,请按以下步骤操作:
- 收集服务器日志、组件控制台日志、ChatGPT 工具调用记录以及屏幕截图。
- 记下您提交的提示词和收到的所有确认消息。
- 将这些信息提供给您的 OpenAI 合作伙伴联系人,以便他们在内部复现问题。
清晰简洁的故障排查记录有助于缩短问题处理时间,让您的 MCP 服务器持续为用户提供可靠的服务。