MCP 工具调用如何做超时隔离：Go 服务的上下文、重试与审计边界

把 MCP 工具接进 Go 服务后，最容易漏掉的不是 JSON-RPC 请求格式，而是“这次调用到底还能等多久”。模型可能先后调用天气、订单、搜索等工具；如果每个工具都自己等 10 秒，一次用户请求很快就会被多个下游拖住。更稳妥的做法是给整条链路一个总耗时上限，再给单次工具调用一个更小的耗时上限，超时、取消和重试逻辑都统一收拢到同一个边界规则里处理。

MCP 的协议消息负责表达工具调用规则，Go 服务仍要自己把控总超时、取消传播、有限重试和审计留痕；这四件事不能直接甩给模型或者下游连接组件处理。

先把一次 MCP 调用拆成四个边界

MCP 的消息遵循 JSON-RPC 2.0，工具服务可以通过 tools/call 对外暴露能力。但在业务服务里，“发出请求”只是中间一步，真正要管理的是以下四个边界：用户请求的总时间、单个工具的调用时间、允许重试的最大次数，以及最终需要留存的审计信息范围。

假设一个问答接口总共最多只能等待 8 秒，天气工具最多占用 3 秒，失败后最多补一次 800 毫秒的重试；即便下游迟迟不返回，父级 context 到期也要让调用流程尽快收尾。这个耗时配额是服务自己定的运行契约，不是依赖对方工具的服务承诺。

Go 包装器：父级总配额，子级单次配额

下面的示例不依赖特定第三方 SDK，先把“调用一个工具”的控制面逻辑梳理清楚。ToolCaller 只接收已经构造好的 JSON-RPC 请求，网络传输部分可以按需替换成 HTTP 或者 stdio 模式；这样超时和审计逻辑不会散落在每个工具适配器的代码里。

type ToolCaller struct {
    Transport Transport
    Audit     AuditSink
    PerCall   time.Duration
    Retries   int
}

func (c *ToolCaller) Call(parent context.Context, traceID, name string, req Request) (Result, error) {
    started := time.Now()
    attempts := 0
    var lastErr error

    for attempts  c.Retries {
            break
        }
        if !sleepWithContext(parent, 120*time.Millisecond) {
            break
        }
    }

    state := "failed"
    if errors.Is(lastErr, context.DeadlineExceeded) {
        state = "timeout"
    }
    c.Audit.Record(traceID, name, time.Since(started), state, attempts-1)
    return Result{}, lastErr
}

这里有两个很容易被忽视的细节。第一，stop() 必须在每轮调用结束后执行，避免定时器一直挂起直到父级 context 到期才释放。第二，重试等待的过程也要监听父级 context 的取消信号；不能因为正在等待 120 毫秒的重试间隔，就让已经被取消的用户请求继续占用协程资源。

重试只处理临时故障，别把业务错误放大

retryable 不应该写成“所有错误都直接重试”。工具参数缺字段、权限不足、资源不存在和业务校验失败这类场景，重试不会改变最终结果，反而会额外增加下游的服务压力。

func retryable(err error) bool {
    var temporary interface{ Temporary() bool }
    if errors.As(err, &temporary) && temporary.Temporary() {
        return true
    }
    return errors.Is(err, io.ErrUnexpectedEOF) ||
        errors.Is(err, context.DeadlineExceeded)
}

实际项目里还要把 MCP 工具返回的结构化错误映射成内部定义的错误类型。例如把“服务繁忙”映射为临时错误，把“缺少城市参数”映射为参数错误。重试次数建议从 0 或 1 开始配置，先观察下游的 P95 耗时和错误比例，再决定是否调大次数，不要默认就配置三次重试逻辑。

权限和参数边界要在工具名之外再检查一次

工具名不等于权限标识。即便模型选择了在白名单内的 weather.lookup，服务仍要校验当前用户、租户、地域和参数范围是否符合规则。审计字段也不要直接写入完整请求体：地址、订单号和搜索词都可能包含个人信息，记录参数摘要或者经过脱敏的关键字段会更稳妥。

• 工具白名单：只允许业务预先登记过的名称，未知工具请求直接拦截拒绝。
• 参数校验：限制字符串长度、枚举值和资源归属范围，拒绝不在定义内的多余字段。
• 凭据隔离：工具服务需要的访问令牌由服务端注入，不从模型输出内容中读取。
• 结果限制：限制单次返回内容的最大体积，避免工具返回结果反过来撑爆上下文内存。

审计记录要能回答“谁、调了什么、结果怎样”

一次调用至少写下 trace_id、工具名、开始时间、耗时、结果状态、重试次数和错误分类。日志里保留 request_id 便于和网关、MCP 服务端的记录串联起来；不要把完整提示词、访问令牌或者未经处理的用户参数直接落盘存储。

type AuditSink interface {
    Record(traceID, tool string, cost time.Duration, state string, retries int)
}

// 典型记录：trace=tr_8f31 tool=weather.lookup cost=842ms state=ok retries=1

如果工具调用跨越多个服务，可以把同一个 trace ID 放进 JSON-RPC 请求的元数据或者传输层的请求头里，具体实现方式按实际传输场景决定。不要默认 MCP 会替你维护业务会话；协议层和应用层的关联关系需要明确写进自己的请求模型里。

上线前用四条测试路径验收

先用 httptest 或者传输层的内存替身固定下游的返回行为，再校验包装器的运行状态和审计记录的次数是否符合预期。

1. 成功：一次返回结果，状态为 ok，重试次数为 0。
2. 临时失败后恢复：第二次调用返回结果，重试次数为 1，总耗时仍未超过父级的总配额。
3. 单次超时：子级 context 到期，状态为 timeout，不会继续等待发起下一轮调用。
4. 用户取消：父级 context 收到取消信号后，状态为 cancelled，重试等待过程立即终止。

发布时把总配额、单次配额、最大返回大小和重试次数都放进配置项里，还可以给每个工具单独设置上限。灰度期间重点观察超时率、取消率、平均重试次数和工具结果大小几个指标；一旦某个工具的重试次数持续上升，先停用重试机制或者降低并发量，不要用拉长等待时间的方式掩盖下游的故障。

常见问题

MCP 自己会替 Go 服务取消工具调用吗？

不能做这种假设。MCP 只规定消息和工具调用的表达方式，Go 服务仍要把请求取消的信号传播到实际传输层和下游客户端。

工具调用超时后应该马上重试吗？

先判断超时发生在连接、传输还是业务处理阶段。只有确认是短暂网络问题且工具操作本身具备幂等性时，才适合做一次小间隔的重试。

审计日志可以保存完整参数吗？

高风险工具不建议直接保存完整参数。优先记录参数摘要、资源类型和校验结果，并且按照数据分级规则设置对应的留存时间。

为什么总超时和单次超时不能只留一个？

只配置总超时会让某个慢工具吃掉全部配额，只配置单次超时又可能让多个工具依次累积超时。父子两层配额才能同时把单次调用的风险和整条请求的用户体验都控制住。

发布检查清单

把工具调用包装成服务边界后，代码审查可以只核对几项硬条件：父级 context 是否贯穿全链路、每次调用是否有子级超时期限、重试逻辑是否做了错误分类、敏感参数是否完成脱敏、审计记录是否能关联 trace ID、四条测试路径是否都覆盖到。满足这些条件，再接入具体的 MCP SDK 或者自定义传输方式，后续替换工具实现时就不会重新写一套重复的超时和日志逻辑。