MCP 工具调用超时,直接说明的是调用方停止等待。排查的第一步是找到最后成功的协议阶段,再把客户端请求与服务端执行日志对上。只有确认哪个计时器到期,调大超时才有明确对象。
本文是操作性排查流程,文档核对日期为 2026 年 11 月 16 日。客户端、SDK 与协议版本会改变配置和行为。先记录客户端版本、服务端版本、SDK、传输方式和实际协议版本,再套用网上的设置。
用最后一个成功事件确定调查方向
| 已确认的最后事件 | 接下来检查 | 有区分力的证据 |
|---|---|---|
| 客户端尝试启动服务,但进程没就绪 | 可执行文件、工作目录、运行时、环境变量 | 退出码和启动 stderr;图形应用与终端可能使用不同 PATH |
| 进程或 HTTP 地址可达,发现阶段没完成 | 认证、协议版本、实际请求与响应 | 请求发出后没有对应响应,或明确认证与协议错误 |
| 已拿到工具列表,函数处理器没进入 | 宿主批准、路由、参数校验、排队 | 客户端派发时间和服务端 handler-entry 时间 |
| 处理器已进入,下游操作没结束 | 数据库锁、API 延迟、线程或 worker 饱和 | 同一请求的下游开始、结束、异常记录 |
| 服务端已完成,客户端仍然超时 | 序列化、代理、回传链路、调用方截止时间 | result-emitted、代理日志、response-received |
这张表用于生成待验证的假设。地址可达只能证明网络路径的一部分;工具能列出来,也不能证明业务操作一定成功。
还要先排除协议代际混用。Legacy MCP 通过 initialize 和 notifications/initialized 进入正常操作;当前 Inspector 文档也包含采用 server/discover 的 2026-07-28 modern 模式。Inspector 默认 legacy,可显式选 auto 或 modern。先匹配被测系统,才能解释为什么某个握手请求没有回应。Legacy 生命周期、Inspector 协议代际说明。
把模型循环暂时移开,先做最小只读调用
使用官方 MCP Inspector,尽量保持与故障宿主相同的命令、工作目录、必要环境变量、地址、凭据与协议模式。先验证发现,再选择明确只读的工具,用最小、已知的参数执行一次。Inspector 官方指南。
官方文档给出的本地 Node 服务工具发现形式是:
npx @modelcontextprotocol/inspector --cli node path/to/server/index.js --method tools/list
路径替换成自己的服务入口。执行软件包会运行其代码,应使用可信、经过审查的包,并记录和固定本次验证的 Inspector 版本。这里展示命令形式,没有声称已经在你的服务上测试。
Inspector 同样失败时,优先调查服务端与传输证据;Inspector 成功时,逐项比较原宿主的环境和请求。换一个客户端成功,提供的是定位线索,仍需用原宿主复现和验收。
stdio 场景还要检查启动包装脚本。欢迎语、调试 print、安装提示如果写入 stdout,可能污染消息流。普通日志写 stderr,stdout 留给协议消息。stdio 规范。
为一次失败建立超时预算表
建议记录如下脱敏时间线。数值是说明用示例,不是本站实测:
关联标识:diagnostic-17
协议 / 传输 / 客户端版本 / 服务端版本:...
发出请求: +0.000 秒
进入处理器: +0.120 秒
开始下游操作: +0.135 秒
调用方停止等待:+10.000 秒
下游结束: +12.400 秒
服务端发出结果:+12.410 秒
业务结果:只读 / 已提交 / 失败 / 未知
单个进程内优先记录单调时钟的相对时间;跨机器对时要考虑时钟偏差。请求 ID 用于串联协议过程,业务操作 ID 用于查最终效果。日志中去掉令牌、敏感参数与私人数据。
把每个计时器的负责组件、单位、起点和重置条件列清楚:启动、排队、SDK 请求、下游请求、代理空闲、宿主整体任务、用户取消。代理的空闲超时与请求总时长上限,计量的可能是两个不同区间。
预算根据预期操作和实测延迟设定。通常需要给服务端留出返回受控下游错误的时间,同时满足外层任务截止时间。这里是工程预算建议,不存在一个适用于所有 MCP 客户端的统一秒数。
进度、取消和重试分别验证
进度通知能提供可观测性,但是否重置等待时间由具体实现决定。Legacy 生命周期规范允许按进度重置计时,同时建议保留总时长上限。要核对客户端是否收到进度、是否真的重置计时,以及其他链路有没有先到期。超时规范。
取消同样有版本边界。Legacy HTTP 断开本身不表示取消;当前 Inspector 文档则把关闭请求自己的 SSE 响应流描述为 modern HTTP 的取消信号。stdio 仍使用取消通知。先确认协议模式,再分析断线意味着什么。Legacy 传输规则、当前 Inspector 取消行为。
取消请求也不能当成业务回滚凭据。Legacy 规范明确考虑了工作已经完成、操作无法取消等情况。写操作超时后,先按业务操作 ID 查最终结果;结果未知就对账。有服务正式支持的幂等机制时再使用,不能凭空加一个 idempotency_key 就假定服务会去重。取消规范。
长任务可以评估双方支持的任务机制,或应用层的提交任务与查询状态设计。需要一起检查能力支持、持久化、取消和结果读取。返回一个 job ID 只是入口,断线后还能找回真实操作才有用。
修复后按故障注入验收
在本地测试夹具或预发布环境中使用合成、只读工作,每次只改变一个变量,保留请求轨迹:
| 注入条件 | 应观察的信号 | 验收要求 |
|---|---|---|
| 故意延迟服务启动 | 发现阶段失败,业务处理器未进入 | 正常启动成功,异常启动有明确且有限的失败窗口 |
| 工具运行超过调用方截止时间 | 处理器开始后,调用方先停止等待 | 合理时长能完成,异常长任务仍受边界控制 |
| 延迟完成但持续发送进度 | 能看到进度,最终结果取决于客户端策略 | 实际重置行为符合配置,总时长仍有约束 |
| 合成操作完成后切断结果回传 | 客户端失败与服务端完成同时存在 | 恢复逻辑先确认结果,再决定是否重做 |
这是建议执行的测试计划,没有把它写成已经完成的实验。执行时填写真实版本与观察结果。Inspector 验证通过后,还要回到原宿主,用新连接完成一次正常只读调用。
完成标准应当能写成一句明确的话:哪一层先到期,如何复现,改了什么,原请求现在返回什么,以及异常情况下如何安全退出。仅仅等待更久,不能说明问题已经解决。
如果问题进一步涉及接口选型,可以继续读 MCP 与 CLI 的执行及信任边界。