-32001 不是普通工具报错
如果日志持续出现 MCP error -32001: Unknown or expired MCP session,但工具列表仍然可见,问题通常在 MCP 连接生命周期,而不是某个参数写错。公开复现中,Harness 在两个回合里重复调用失效工具,累计产生数万条事件,却没有重新初始化连接或刷新工具列表。
先停止会继续写入的 Agent 回合
遇到同一错误连续出现时,先取消当前回合,暂停后续 prompt,禁用产生错误的 MCP 条目。不要让 Agent 自动重试写操作;失效 session 下的重放可能造成重复提交或重复扣费。
保留以下脱敏字段:
- MCP 传输类型:stdio、SSE 或 Streamable HTTP
- session ID 的哈希值,不要保存原值
- 第一次
-32001的时间和工具名 - 重试次数、回合耗时和是否产生写入
验证是否真的完成了重连
重新启用 MCP 后,不要只看工具名称重新出现在 UI。成功的初始化至少应包含:
- 新的连接代际或 session ID。
- 一次完整的
initialize。 - 一次新的
tools/list。 - 一个无副作用的只读验证调用。
如果 session ID 没变、工具列表没有刷新,说明仍在使用旧连接。
自动重试应该有边界
对 -32001 这类确定性会话错误,安全顺序是“撤销旧工具、单次重连、重新发现工具、失败后熔断”。只有只读或明确幂等的操作才适合在新连接上重试。原始失败调用不要自动重放,尤其是提交、发送、删除和部署类工具。
成功标准
恢复后,旧工具调用停止增长,新工具列表来自新 session;相同错误不会超过一次重连窗口;写操作需要重新获得权限或由用户确认。若只能通过重启整个 Harness 恢复,应把它记录为运行时恢复缺口,而不是网络偶发抖动。
这条路径与 MCP 安装前的 tool poisoning 检查不同,重点是运行期失效、连接代际和重试熔断。