让 Cursor 稳定调用 MCP 的排障思路

Cursor 的 Agent 明明有可用的 MCP 工具，却绕开它手写 fetch，问题可能出在工具描述、一次超时，或者输入不符合 schema。作者的结论是：别只修生成的请求，要修好工具，并让绕过工具的调用无法通过检查。

这篇文章值得读的地方，是把一次险些合并的错误，拆成了工具设计、错误恢复和工程约束三个问题。对正在给 AI 编程助手接内部 API 的团队，这比再加一句「必须使用工具」更有参考价值。

一次超时，为什么会变成一个错误请求

作者在代码审查中遇到过这样一件事：Agent 原本应该通过 MCP 暴露的工单工具创建 ticket，第一次生成代码时也确实调用了工具。但在后续任务里，它改成了手写 fetch。

这段请求硬编码了 URL，手动拼装 bearer token，还使用了 API 在两个发布版本前就已更名的字段。追查后发现，Agent 曾调用工具并遇到一次临时超时，之后便自行选择了直接请求。

结果是，一个注定返回 HTTP 400 的请求差点被合并。代码看起来合理，测试却没有覆盖这条路径。

作者据此列出了四类常见诱因：

• 工具描述太模糊，例如只写「管理 issue」，Agent 未必能将「创建 ticket」对应到它。
• 当前会话里出现过调用失败，Agent 随后倾向于绕过工具。
• 手头数据不符合输入 schema，Agent 选择另写请求，而没有调整数据。
• 暴露的工具太多，名称又相近，正确操作被埋在列表里。

这里的「学会绕过」，更适合理解为 Agent 根据当前上下文改变了选择。原文没有证据表明，一次超时会让模型发生持久的训练更新。

工具可用，不等于工具会被选中。

fetch 是模型熟悉的通用路径。专用工具如果没有清楚表达自己能做什么、失败后怎么办，就可能在选择中输给它。

先让工具容易选，再让错误容易恢复

作者把修改工具描述放在第一步：明确写出资源、动作，以及应该在什么情况下使用它。

对工单系统而言，「管理 issue」提供的信息很少；描述需要让 Agent 看出，这个工具对应的就是创建工单这项操作。目的不是增加文字量，而是减少从用户意图到工具能力之间的猜测。

工具列表也需要收敛。作者偏向少量职责清晰、名称明确的操作，而不是把大量相似接口全部暴露出来。不过，原文没有给出工具数量与成功率的对照数据，这属于设计经验。

第二步是处理曾经导致绕行的错误。

如果诱因是超时，就应该调查超时原因，设置合理的时间限制，并返回结构化、可判断是否重试的错误。大白话讲，工具不能只说「失败了」，还要让调用方知道，这次失败是否值得再试。

如果诱因是 schema 不匹配，就先把输入调整到已验证的格式。只有业务上合法的数据确实无法表达时，才有理由有意识地扩展 schema。

临时故障应该进入恢复流程，而不是自动变成绕过接口契约的理由。

原文没有提供超时阈值、重试次数或错误结构示例。因此，它给出了排查方向，还没有给出能直接复制的恢复方案。

为什么还要让绕行请求过不了检查

在作者讨论的系统里，MCP 工具集中承载认证、基础 URL、schema 校验和日志。手写请求则重新承担这些责任，也重新引入旧字段、错误地址和认证拼装失误。

所以，修描述之外，还要设置工程边界。

作者建议，在审查规则中标记所有直接访问已被 MCP 工具覆盖的 host 的 HTTP 调用；测试则明确断言相关功能使用了工具。最后，再根据接口契约验证生成的请求，防止过期字段藏在工具调用背后。

这几层检查解决的是不同问题：调用路径检查负责发现绕行，工具使用断言负责约束实现，请求契约检查负责发现格式错误。只验证业务结果，很可能漏掉一段尚未执行过的错误请求。

作者的边界很严格：只有目标 host 没有 MCP 覆盖时，手写 fetch 才可以接受。这个判断体现了他希望把接口访问统一收口的立场。

我的判断

我赞同作者把问题从「模型不听话」转向工具设计和工程约束。尤其是创建工单这类操作，认证和字段格式已有统一入口，再生成一套请求逻辑，会增加维护负担。

但有两个前提需要拆开。

首先，认证管理、schema 校验和日志是这套 MCP 服务承担的能力，不能仅凭一个接口被包装成 MCP 工具，就认定它已经具备这些保障。原文没有展示服务实现，读者需要检查自己的工具究竟做到了哪一步。

其次，「有 MCP 覆盖的 host 一律禁止直连」可能过粗。同一个 host 下，工具未必覆盖全部业务操作。实际落地时，规则最好对应已覆盖的 API 范围，否则可能把必要调用也拦住。

相比只在提示词里强调使用工具，作者提出的检查和测试更容易验证。不过，「改描述最快、最有效」以及「结构化错误能让 Agent 留在工具内恢复」，都没有配套对照实验。它们值得尝试，不能当成已被量化证明的结论。

能拿来做什么

• 给 AI 编程助手接入内部 API 时，检查工具描述是否明确写出资源、动作和使用条件，并用团队日常提需求的措辞验证它能否被正确选中。
• 当 Agent 突然生成直接请求时，先查看当前会话中的工具调用记录，确认是否发生过超时、其他错误或 schema 不匹配，再修改对应环节。
• 在 Node 服务或自动化脚本的审查中，检查指向已覆盖 API 的直接 HTTP 调用，并让相关测试验证工具调用路径和请求字段。
• 在限制直连之前，先列清 MCP 工具实际覆盖的 API 范围及其认证、校验、日志能力，让检查规则与真实保障一致。