工具调用超时并非只有一种：四种故障模式与恢复路径

“Timeout”是Agent框架报告工具调用失败时用得最多的一个词，但它掩盖了至少四种完全不同的故障。其中最危险的一种，恰恰被错误地当作超时来处理，导致付费、非幂等的调用被重复执行。

为什么“超时”是一个误导性的词

每个Agent框架都为工具调用设了一个不可逾越的时间上限。当长调用触碰到这个上限时，框架只抛出一个词——timeout——而Agent通常只做一件事：再调一次。

如果这个工具是付费且非幂等的，这就是最糟糕的响应，因为第一次调用往往已经执行完毕。原文作者维护了一个设计上就需要 180–300秒 的决策端点。这个长调用是刻意的，而且工具schema里的任何参数都无法让它变短：限制存在于客户端，而不是调用本身。

正因如此，同一个故障会以四种不同的形态到达，每一种都需要不同的应对策略。

MCP（Model Context Protocol） 是 Anthropic 于 2024 年底提出的开放协议，用于让 AI 应用（宿主）以统一方式连接外部工具与数据源。它采用客户端—服务端架构：MCP 宿主（如 Claude Code、Cline、Cursor）内置 MCP 客户端，通过 stdio 或 HTTP/SSE 等传输层与 MCP 服务端通信。工具调用即客户端向服务端发送 tools/call 请求。理解这一点很关键：超时计时器运行在客户端一侧，服务端只是被动接收请求并返回结果，因此服务端无法通过参数“放宽”客户端的限制——这正是本文反复强调“限制存在于客户端，而不是调用本身”的协议层原因。

四种“超时”，四种信息量

原文给出的决策表把四种情况拆得很清楚：

• 客户端主动中止调用（触发自身限制）：任务通常已经在服务端跑完。此时不应重试，正确做法是按id取回结果；如果拿不到id，就列出当前凭证创建过的任务。
• 服务端返回错误结果（isError: true）：任务被拒绝或执行中出错。是否重试取决于错误块中的HTTP状态码，而不是“timeout”这个词本身。
• 框架把调用转为后台任务并返回任务id：任务确实在执行。不要重试，等待任务通知或按id取回即可。
• 空闲中止（idle abort）：调用在空闲窗口内没有发出任何内容。任务通常已完成，同样不应重试，按id取回。

这四种里，前两种看起来像超时但其实不是，第三种根本不是故障而是框架的礼貌处理，而第一种最烧钱：答案已经存在、已经付过费，Agent却因为“timeout”这个词又调了一次。

幂等性（Idempotency） 是指同一操作执行一次与执行多次对系统状态产生的效果相同。查询、读取类操作天然幂等，重复执行无副作用；而支付、下单、创建任务、发送消息等操作通常非幂等——每执行一次就产生一次真实副作用（扣费、生成新任务、发出消息）。在分布式系统中，当调用方无法确认请求是否已被服务端处理时，盲目重试非幂等操作是经典反模式，可能导致重复下单或重复扣费。业界通常的解法是为每次请求分配唯一幂等键（idempotency key），服务端据此去重；而本文提出的“按 id 取回”本质上就是让客户端通过任务 id 查询结果，从而在非幂等场景下安全地避免重试。

各客户端的实际行为差异

超时处理不属于传输层行为，因此MCP规范在这里给不出任何承诺。原文作者根据各客户端自己的文档整理了如下差异：

• Claude Code：启动/连接用MCP_TIMEOUT（毫秒）；每次工具调用用.mcp.json中的per-server timeout字段（毫秒），会覆盖MCP_TOOL_TIMEOUT，未设置时约28小时；空闲窗口对HTTP/SSE为5分钟，对stdio为30分钟，可用CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT调整，设为0则禁用。此外，运行超过2分钟的调用会转入后台任务，通过任务通知报告。
• Cline：在cline_mcp_settings.json中用timeout字段配置，单位是秒。历史上存在一个bug（issue #2296），无论设置如何，调用都可能在60秒左右死亡。
• Cursor / Windsurf / VS Code：MCP页面中未记录相关配置。原文建议把传输/客户端默认值视为未知，不要调整你看不见的东西。

这里有两点比表格本身更重要。

第一，实际触发的往往不是墙钟时间限制。 在HTTP连接上，Claude Code还会跑一个per-request计时器，起点是60秒、服务端工具超时、MCP_TIMEOUT三者中的较大值，但这个计时器在第一个响应字节到达时就停止了。一个思考五分钟再回答的服务端，实际上是在和空闲窗口赛跑，而不是墙钟窗口。

第二，空闲窗口才是惩罚“慢但正确”工具的那一个。 一个工具调用如果在空闲窗口内没有发送任何响应和进度通知，就会被中止，无论per-call限制多宽松。如果你的工具需要几分钟且中途不发任何东西,真正的天花板就是空闲窗口——Claude Code上HTTP为5分钟——而这个数字你可能从未见过,因为它就写在你要找的那个超时配置的隔壁页。

缓解措施很便宜，而且就在同一份文档里：per-server timeout至少设为1000毫秒时,也会作为空闲超时的下限。所以长调用的实际配置不是“把大数字调高”，而是给对应server设置一个足够大的timeout值（例如600000毫秒）。注意这个值在空闲比较中是更小的那个数,复制数字前请先读客户端自己的MCP页面。

空转（idle）与墙钟（wall-clock）超时的区别是理解本文的关键。墙钟超时从请求发出起计时，无论中途是否有数据流动；空闲超时则只在两次数据流动之间的静默期计时，一旦收到任何响应字节或进度通知就重置。对于“思考很久但最终会回答”的服务端，墙钟窗口可能早已耗尽，而空闲窗口才是真正裁决者。此外，stdio 传输通过标准输入输出在本地进程间通信，延迟低但受宿主进程生命周期约束；HTTP/SSE 传输走网络，SSE（Server-Sent Events）允许服务端单向流式推送，天然具备中途发送进度通知的能力。这两种传输在空闲窗口设置上通常不同，这也是 Claude Code 对 HTTP/SSE 设 5 分钟、对 stdio 设 30 分钟的原因。

取回路径，以及它会在哪里断掉

如果调用是在服务端接受之后被切断的，正确的原语是取回调用（retrieval），而不是第二次调用。原文建议把取回做成一个工具，而不是让Agent用curl去干。

• 有id时：返回任务状态，完成后返回原调用本该返回的payload。
• 无id时：返回该凭证最近创建的id列表。这是最关键的情况，因为客户端中止永远不会给你id。
• 只读且免费，所以重复调用永远安全。取回调用没有理由计费或涉及幂等性。
• 凭证留在宿主端。 在MCP宿主内，Agent通常不持有API key，因此在Agent内部直接用厂商REST API做取回会得到401，而通过工具表面却能正常读取。把key放进工具参数会把它推进prompt和transcript里，这是必须避免的。

两个值得复制的服务端实现细节：

“不是你的”和“不存在”要返回完全相同的响应。 如果两者有差异，取回端点就会变成探测其他租户任务id的预言机。同样的状态码、同样的body，并且要把这条规则写进工具描述里，否则未来的维护者会把它“修”成一个漏洞。

明确声明保留窗口，并把空列表作为正常结果返回。 原文作者的服务器保留id 7天，对未知id和他人id给出相同答案。空列表不是错误，也不存在“id 0”哨兵值；一旦你发明一个，每个客户端最终都会去探测它。

在使用取回路径之前先测试它

这是最常被跳过的一步，只需二十秒：在一切正常时，不带参数调用取回。

• 返回401或unauthorized：取回从Agent运行的位置不可达。你的恢复计划只是图上的一个框，不是真正的能力——在需要它之前先修好可达性。
• 成功但返回空列表：凭证有效、端点响应、空窗口被正确处理。这正是第一次被切断之前你想要的状态。
• 成功且返回id：取回端到端可用。取回最老的id并确认payload与调用本应返回的一致。

在自己的harness里跑一次，并把结果记录在工具描述里，这样下一个读到工具列表的Agent就知道它是能取回还是只能重试。工具描述是恢复策略无需任何代码就能触达模型的唯一位置。

设计结论

对于任何非幂等且付费的操作，要让重试不可能被意外选中：

1. 每个结果都返回id，包括成功的那些。 只在失败时发放的id等于没人记录的id。
2. 在工具描述里写明预期时长——“预留180–300秒”不是营销话术，它是客户端停止切断调用所需的数字。
3. 说明超时是客户端设置，不是参数。 一个相信自己可以传timeout: 300的Agent会永远传下去，而实际行为从不改变。
4. 让取回只读、免费、幂等，并且从Agent一侧无需凭证。
5. 把“不是你的”规则写进契约，让答案对陌生人保持无信息量。

原文作者运行的实现位于https://mcp.turingcorp.net，其tools/list按设计是开放的，因此无需凭证就能读到恢复契约，包括取回工具和180–300秒的预期。