Codex MCP 报错 Unexpected response type

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 至少出现了三类兼容问题：

1. 合法的工具结果被 MCP 库解析成 CustomResult，Codex 只接受预期的 CallToolResult。
2. content 中包含 resource_link 时失败，只返回普通 text 时成功。
3. 结果中的 annotations、structuredContent 或特定组合触发解析差异。

这些案例说明 Unexpected response type 是一层通用报错，不能只凭这一句话断定具体是哪个字段。服务端返回了非法 JSON、使用了不匹配的 MCP 协议版本，也可能产生相似结果。

快速排查

1. 运行 codex mcp list，确认服务处于 enabled 状态。
2. 记录失败的 MCP server 名、tool 名、Codex 版本和传输方式，例如 stdio 或 Streamable HTTP。
3. 用 MCP Inspector、服务端自带客户端或直接 JSON-RPC 调用同一个工具。
4. 如果其他客户端成功、只有 Codex 失败，重点看 Codex 与返回结构的兼容，而不是反复登录。
5. 如果所有客户端都失败，先修 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 修复还是短期回退版本。