让智能体读懂 MCP 工具的错误与限制
作者分享了 MCP 服务的实现经验,包括在执行前检查权限并返回结构化原因,以及在数据缺失时明确指出依赖。文章还提醒,客户端可能拒绝未知的协议版本。
AI 深度解读
当客户从读 API 文档的开发者变成直接调用工具的 Agent,接口得把三件事说清楚:为什么调用被拦、哪些数据还没准备好、客户端能不能连上。作者用自己提供薪酬数据的经历说明,权限、缺失字段和协议版本,都会影响 Agent 能否正确处理一次调用。
这篇最值得拿走的是接口设计上的三个改动。哪怕入口还是普通 API,只要下游开始自动调用,这些问题就已经存在。
工具执行前,就把拒绝原因交代清楚
作者把权限检查放在所有工具的执行之前。调用不满足条件时,工具会返回结构化原因,区分套餐级别不足和缺少权限范围(scope),并指出具体缺了什么。
这样的错误能帮 Agent 决定下一步。缺少某个 scope,可以把具体权限交给用户处理。套餐不够,则可以提示当前账户的限制。只返回「出了点问题」,Agent 就缺少判断依据,既不知道重试有没有用,也不知道该请用户补什么。原文没有给出错误对象的字段定义。
数据没准备好,就把缺失原因一起返回
依赖的数据还没到位时,作者让工具把对应字段留为 undefined,同时在限制说明里点名缺失的依赖。Agent 拿到一个看似合理的猜测,可能直接把它带进后续决策。明确指出数据缺在哪里,至少给下游留出了暂停或调整流程的依据。
前端和 Node 开发者还得留意传输这一层。JavaScript 对象里的属性值是 undefined 时,经过常规 JSON 序列化,该属性会被省略。作者没有交代客户端最终收到的结构,所以实现时要检查限制说明是否随响应一起抵达,以及 Agent 能否把说明和缺失的字段对应起来。
协议版本不匹配,工具逻辑可能根本跑不到
据原文,MCP TypeScript SDK 的 npm 周下载量超过 4300 万。Anthropic 推出 MCP 后不到一年,OpenAI 和 Google 都采用了这个协议。这些数字说明了协议的采用情况,实际接入仍取决于客户端支持哪些版本。
作者在提供覆盖 3,445 个岗位的 1,500 万条薪酬数据时,遇到过 MCP 客户端直接拒绝未知协议版本的问题。连接如果在版本检查时就被拒绝,后面的权限检查和数据返回都不会执行。原文没有说明触发问题的版本号、客户端组合或修复方式。
我的判断
把错误做成可供程序判断的结果,是这篇最扎实的建议。普通 API 也可以用稳定的错误码和字段表达缺少哪个 scope、哪项数据暂不可用。MCP 接入是否值得做,还得看目标客户端和团队需要维护的兼容范围。原文给了下载量和作者踩过的版本问题,却没有提供 MCP 与常规 API 的对照数据,也没测量结构化错误能减少多少失败。这部分应当按工程经验来读。
能拿来做什么
- 给 Node 工具处理器加执行前的权限检查,分别返回套餐不足和缺少 scope 的原因,并在响应中写明缺失的具体权限。
- 为依赖数据未就绪的情况补一条端到端用例。检查序列化后的真实响应,确认客户端能识别哪个字段缺失以及它依赖什么。
- 把 MCP 连接纳入发布前验证,用实际支持的客户端完成一次连接和工具调用,再用不受支持的协议版本检查客户端的拒绝行为。