MCP 工具静默消失的 5 种方式:Claude、Cursor、ChatGPT 各有坑

Future_AGI · reddit · 2026-10-13

作者综合多个真实案例,总结了 MCP 工具在客户端「无声消失」的 5 种方式——不会报错,只能靠主动检查发现:

inputSchema 根节点带 oneOf:规范允许,但 claude.ai connector 和 Cursor 会直接丢弃该工具(ChatGPT 保留)。建议根节点保持普通 object,把 oneOf 下移到属性里。
Python SDK 的 x-mcp-header 注解类型不合法:v2.3.0 之前注册不报错,但客户端按新规范会从 tools/list 里剔除;除 str/int/bool 外的类型(含 str | None、float、列表、枚举)都算非法。v2.3.0(10 月 2 日)改为注册时直接拒绝。
工具命名问题:OpenAPI 生成器产出 ids[] 这类名字会被 Claude Code 丢弃;过长名字或带点的名字也可能被截断或拒绝。
工具数量超限:某服务器在 Claude/OpenCode 可见 109 个工具,ChatGPT 只显示 43 个、止于字母 K。有人推测是 tools/list 字节预算;且 ChatGPT 在安装时缓存 tools/list,改动后需移除重连。
客户端更新:「Codex 更新后除非明确要求否则不再调用我们的工具」——客户端版本才是决定工具消失的变量,每次测试都应记录版本号。

核心教训:被丢弃的工具从不产生失败调用,任何报警都没有。排查方法是每次 schema 变更或客户端更新后,逐个客户端列工具清单并跑真实任务看模型选了哪些。作者的开源 eval 工具带有 toolselectionaccuracy 检查,可离线给 agent 是否漏用必需工具打分。

「编程与Agent」频道最新