Codex MCP 报错 Unexpected response type
如果 MCP 工具能被发现、调用后才报 Unexpected response type，问题通常在工具结果的解析或兼容层，不应先归因于登录、权限或模型。先用同一工具做客户端和版本对照。
错误摘要
Codex MCP 报 Unexpected response type 时，先确认错误发生在 tools/call 返回之后，再用 MCP Inspector、直接客户端或旧版 Codex 做对照；服务端可临时简化返回内容，普通用户则应保留版本和工具名等待兼容修复。
Codex 能看到 MCP 工具，但调用时返回：
Error: tool call error: tool call failed for `<server>/<tool>`
Caused by:
Unexpected response type这个错误是什么意思
Unexpected response type 表示 Codex 收到了 MCP 调用结果，但没有把它识别为当前 tools/call 路径能够接受的结果类型。
这和“工具不存在”不同：工具已经被发现并发起调用，失败发生在结果返回之后。也不要先把它解释成 API Key、MCP OAuth 或模型权限问题，因为已公开案例中，同一个 MCP 服务通过直接客户端或其他 MCP 客户端可以正常返回结果。
已确认的触发场景
公开 issue 至少出现了三类兼容问题：
- 合法的工具结果被 MCP 库解析成
CustomResult，Codex 只接受预期的CallToolResult。 content中包含resource_link时失败，只返回普通text时成功。- 结果中的
annotations、structuredContent或特定组合触发解析差异。
这些案例说明 Unexpected response type 是一层通用报错，不能只凭这一句话断定具体是哪个字段。服务端返回了非法 JSON、使用了不匹配的 MCP 协议版本，也可能产生相似结果。
快速排查
- 运行
codex mcp list，确认服务处于 enabled 状态。 - 记录失败的 MCP server 名、tool 名、Codex 版本和传输方式，例如 stdio 或 Streamable HTTP。
- 用 MCP Inspector、服务端自带客户端或直接 JSON-RPC 调用同一个工具。
- 如果其他客户端成功、只有 Codex 失败，重点看 Codex 与返回结构的兼容，而不是反复登录。
- 如果所有客户端都失败，先修 MCP 服务本身，不要套用 Codex 回归结论。
服务端开发者可以做一次最小 A/B：先只返回一个 text 内容块，再逐项加入 structuredContent、annotations 和 resource_link。哪一步开始失败，哪一项就是当前兼容边界。
怎么解决
你只是 MCP 使用者
先升级到最新稳定版 Codex，再用新任务复测。如果问题仍在，临时停用这个 MCP 工具或改用能正确处理该结果的客户端，并把以下信息提交给 Codex 和 MCP 服务维护者：
- 完整错误原文；
- Codex 版本；
- MCP server 与 tool 名；
- stdio 或 HTTP 传输方式；
- 同一工具在 MCP Inspector 中是否成功。
不要因为 Unexpected response type 就重置账号、扩大 Full Access 权限或更换模型，这些动作通常没有触及工具结果解析层。
你维护 MCP 服务
如果业务允许，可临时把结果简化为标准 text 内容，或移除触发问题的可选 resource_link、annotations。这只是兼容性绕过，不应长期牺牲协议能力。
Eclipse MCP 的公开案例显示，Codex 0.138.0 可用，从 0.139.0 开始失败。可以用旧版做一次 A/B 来证明版本回归，但不要把降级写成适用于所有 MCP 的永久修复。
一句话结论
Codex MCP 的 Unexpected response type 通常是工具结果解析或协议兼容问题：先证明同一工具在其他 MCP 客户端是否成功，再决定修服务端返回、等待 Codex 修复还是短期回退版本。