MCP 工具调用超时怎么收口：错误返回、重试边界与人工接管

接入 MCP 工具后，最难排查的故障往往不是“工具不可用”，而是请求已经发出，模型端却在等待一个迟迟没有回来的结果。此时如果网关、Agent 编排器和工具服务各自重试，原本一次查询可能变成三次写入；如果一律不重试，又会把短暂网络抖动直接暴露给用户。处理超时的关键，是先保护资产，再区分错误，最后把不确定状态交给人工确认。

先把真正需要保护的资产列出来

工具调用看上去只是模型与服务之间的一次往返，实际可能触碰订单、工单、文件、数据库或外部通知。超时策略如果只看网络耗时，不看动作后果，很容易把“查询超时”和“扣款超时”放在同一条重试规则里。

可以先按资产和动作做一张小表：只读查询主要保护可用性，创建、修改和发送动作还要保护一致性，删除和对外通知则需要更高的确认等级。每次调用至少记录工具名、参数摘要、调用编号、发起时间、截止时间和当前状态；敏感参数只存脱敏摘要，不要把完整凭据写进日志。

沿着调用路径定位超时发生在哪一层

一次调用通常经过模型生成工具参数、客户端发起请求、MCP 服务校验输入、业务系统处理、结果返回和模型继续推理几个阶段。任何一段超过自己的预算，都可能让上层只看到一个笼统的 timeout。

建议给每一段单独留出时间预算。例如总预算 8 秒时，参数校验 500 毫秒、连接建立 1 秒、工具处理 5 秒、结果回传和编排收尾 1.5 秒。这里的数字只是示例，重点是让日志能回答“谁先超时”。不要让每层都使用 8 秒，否则最外层以为还有时间，内部却已经重试了多轮。

{
  "call_id": "call_20260827_0142",
  "tool": "ticket_lookup",
  "deadline_ms": 8000,
  "phase": "tool_processing",
  "elapsed_ms": 5120,
  "state": "unknown"
}

上面的 unknown 很重要：客户端没有在截止时间前拿到回应，只能确认“结果未知”，不能直接写成 failed。如果工具服务随后补发完成事件，状态机仍应有位置接住它。

按错误性质划分风险等级

MCP 规范把错误分成协议错误和工具执行错误。找不到工具、请求结构不合法这类问题属于协议层，重试通常不会改变结果；参数不符合业务规则、外部 API 暂时不可用，则可以作为工具结果中的错误信息返回，让上层决定是否修正参数或稍后再试。

工程上还应增加一层“动作风险”判断：读取动作的超时可以进入短暂重试，幂等写入可以在确认幂等键后重试，非幂等写入和外部通知则先查询状态，再决定是否补偿。不要因为错误文本里出现“temporary”就盲目重发，先问清楚服务端有没有接受过这次请求。

重试要绑定幂等键和次数预算

对于读取工具，可以使用指数退避和很小的次数上限，例如最多两次，每次重试都带相同的业务查询标识。对于写入工具，幂等键要由业务意图生成，而不是每次调用临时生成随机数；否则服务端无法判断两次请求是否是同一个动作。

type ToolAttempt struct {
    CallID      string
    Idempotency string
    Risk        string
    DeadlineMs  int
    Attempt     int
}

func canRetry(a ToolAttempt, knownState string) bool {
    if knownState == "accepted" || knownState == "completed" {
        return false
    }
    return a.Risk == "read" && a.Attempt 

示例里的判断顺序是刻意的：先排除已经接受或完成的请求，再看动作风险和次数。退避时间也要计入总截止时间，不能每次重试都重新获得一整段预算。

把超时后的人工接管做成明确状态

人工接管不是一句“请稍后联系管理员”，而是一个可恢复的状态。记录里应包含用户想完成的动作、模型生成的参数、工具返回的最后一条证据、当前不确定点和建议的确认入口。对用户展示时，可以说明“请求可能已经提交，系统正在确认结果”，而不是直接承诺成功或失败。

如果工具支持状态查询，应优先查询原调用编号；如果不支持，就把后续自动动作冻结，避免同一个订单、工单或通知出现重复操作。人工确认完成后，再将最终结果写回会话，并保留谁确认、何时确认、依据是什么。

用审计记录验证收口是否可靠

上线前不要只测成功路径。至少准备四组测试：工具在连接前失败、工具已接受请求但响应丢失、工具返回业务校验错误、工具处理时间超过预算。每组都检查调用状态、重试次数、幂等键、用户提示和人工队列是否一致。

日志关联建议同时保留内部 call_id 与供应商或外部系统的请求编号。像 X-Client-Request-Id 这类客户端关联字段可以帮助排查“客户端没收到响应但服务端已经处理”的情况；不要把它误当成幂等键，追踪标识与业务去重标识解决的是两件事。

常见问题：超时处理中的几个边界

超时后立刻再调用一次可以吗？

只有在确认原请求未被接受，或工具明确支持幂等重放时才可以。否则先查询状态，尤其是创建、扣款、发消息等动作。

工具返回错误要不要让模型自己重试？

可以把可修正的输入错误交给模型，但要设置动作白名单、循环次数和总时间预算。协议错误、权限错误和高风险写入不应由模型无限尝试。

人工接管后还需要保留模型原始参数吗？

需要。参数摘要、版本、调用编号和工具结果是复盘依据；敏感字段应脱敏或加密，不能为了审计把访问凭据原样落盘。

发布前检查这条收口链

一套可用的 MCP 超时方案，最终应能把一次异常还原成清晰的事件链：谁调用了哪个工具，动作是否被接受，哪一层先超时，是否允许重试，最后由系统还是人工确认结果。把资产风险、错误类型、幂等键、时间预算和审计字段放在同一个状态模型里，超时就不再是一个模糊的红色告警，而是一个有下一步、有边界、能安全恢复的流程。