快速结论:该问题出现在 LiteLLM Router 对 MCP 工具调用开启自动执行后,工具已成功写入但后续模型续写失败并触发重试,导致 Router 重放整个 MCP 循环,同一个副作用工具被重复执行(例如 num_retries: 2 下实际写入 3 次,客户端只收到 1 个 HTTP 500)。优先排查:是否存在非幂等 MCP 工具、是否开启 Router 重试、失败是否发生在工具执行之后的续写模型调用上。
适用环境:Issue 明确记录的环境为 LiteLLM v1.102.1;Python 3.12.13,OpenAI SDK 2.54.0,MCP SDK 1.30.0;测试主干提交 2701e2008baee4ed2c16cba7a56ea7f96d6d0981(报告版本 1.104.0,MCP SDK 2.2.0)。客户端走 OpenAI Chat Completions 方言(POST /v1/chat/completions),客户端 SDK 重试 max_retries=0,Router 使用默认或显式 num_retries: 2。MCP 传输为 HTTP。Issue 未提供操作系统与显卡信息。
最快修复方案:暂无确认的一步修复方案。Issue 讨论中倾向的修复方向是:在工具调用派发前标记 tool_call_id 为已提交,后续模型续写出现可重试错误时只重试续写调用、复用已存下的 tool_results,不再重放整个 MCP 循环。该结论来自讨论与代码路径分析,Issue 中未给出已验证的补丁。
注意事项:向 MCP 服务端传 idempotency_key(工具名 + 规范化参数 + tool_call_id)只能作为纵深防御,且仅当服务端真正实现幂等时才有效,不能替代 Router 侧的修复。此外,即使重试被正确禁止,工具已提交而续写失败时,客户端仍只拿到错误、无法从响应中看到已提交的工具结果;这属于运维对账问题,不代表写入被回滚。
问题场景
在 LiteLLM Proxy 中通过 mcp_servers 接入一个由 Proxy 托管的 MCP 工具,并设置 require_approval: "never" 让 Router 自动执行工具;litellm_settings 中配置了 num_retries。当日志中的流程为“初始模型调用 → MCP 工具执行成功 → 后续模型续写调用失败”时,Router 会把整个 MCP 循环视为可重试单元并完整重放,已完成的工具被再次执行。Issue 复现使用的是真实的 LiteLLM Proxy CLI、真实 MCP HTTP 路径、真实 OpenAI Python SDK,以及一个确定性的本地 OpenAI 兼容上游,以便把重试边界与上游随机性隔离开。
报错原文
[Bug]: Router retries re-execute auto-approved MCP tools after a failed follow-up model call
Actual behavior: with num_retries: 2, one initial model call, one MCP write, and one failed follow-up model call are followed by two complete retries. The MCP consumer ledger records three writes and the proxy returns HTTP 500.
原因分析
可能原因:Router 的重试粒度覆盖整个 MCP 处理循环,而不是只覆盖失败的模型续写调用。Issue 评论引用的非流式代码路径为 litellm/responses/mcp/chat_completions_handler.py:先等待 LiteLLM_Proxy_MCP_Handler.execute_tool_calls(...),再构造 follow_up_messages,然后在 internal_sub_call() 中单独等待 litellm_acompletion(**follow_up_call_args)。工具结果与 mcp_call_results 元数据要等续写返回 ModelResponse 之后才被附加;续写失败时,这次已提交的副作用既没有正确阻止外层重试,也没有回传给调用方作为证据。
环境排查
- 确认 LiteLLM 版本(Issue 中为
v1.102.1,并在主干的1.104.0上复现)。 - 确认
litellm_settings.num_retries的取值,以及客户端 SDK 是否额外做了重试(Issue 中max_retries=0)。 - 确认 MCP 工具是否具备幂等性(如写工单、发通知、记账、支付等副作用)。
- 确认 MCP 工具的审批配置是否为
require_approval: "never"。 - 确认 MCP 传输方式(Issue 中为 HTTP)与 MCP SDK 版本(
1.30.0/2.2.0)。 - 确认 Python
3.12.13、OpenAI SDK2.54.0等依赖版本是否与复现环境一致。 - 确认失败发生在工具执行之后的续写调用,而不是工具执行之前或执行过程中。
解决步骤
- 先固定观测手段:在 MCP 工具一侧用独立的、不依赖模型文本或 Proxy 日志的本地账本记录每次真实
tools/call,作为“实际写入次数”的唯一依据。 - 复现最小场景:让初始模型调用固定返回同一个工具调用,工具执行成功后让后续续写调用的上游确定性地返回失败,并设置
num_retries: 2,对比账本条目数与客户端最终收到的 HTTP 状态。 - 核对重试边界:结合
litellm/responses/mcp/chat_completions_handler.py中的execute_tool_calls→follow_up_messages→internal_sub_call()流程,确认失败点位于续写调用,并判断重试是否重放了已提交的工具调用。 - 可优先尝试的缓解措施:在等待修复期间,对涉及副作用的 MCP 工具降低或临时关闭 Router 重试,并让 MCP 服务端自身支持幂等(基于工具名 + 规范化参数 +
tool_call_id的去重键),以减少重复写入。该做法是缓解而非修复,Issue 中未验证。 - 可优先尝试的修复方向(讨论提出、Issue 中未验证补丁):在派发前把
tool_call_id标记为已提交,后续出现可重试错误时只重试续写调用,并复用已保存的tool_results。 - 补充回归用例:同一轮包含两个工具调用,第一个提交成功、第二个失败时,修复后重试应只执行第二个;以及续写失败时留存可关联的“效果回执”(trace/request + 工具调用 + outcome=committed),工具派发后无法确定是否提交的标记为 UNKNOWN 并要求人工对账,而不是按失败或未执行处理。
验证方法
使用同一确定性复现:续写调用失败且 num_retries: 2 时,本地账本中应只有 1 条记录,且没有触发额外的 tools/call;同时应能通过可持久化、可检查的效果回执确认该工具调用已提交,即使客户端最终收到的是错误响应。另做一组不产生写入的对照:在 execute_tool_calls 之前就让首次模型调用失败,此时重试应安全且不产生任何“已提交”回执。Issue 中未记录当前主干已通过上述验证。
参考来源
AI 工具推荐
想把多个 AI 模型放在一个入口?
GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。
推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。
这个方案解决了吗?
可以继续搜索完整报错,或查看同一工具的其他排查指南。
![[Bug] `WebBrowsingManifest.systemRole` caches `Current date` at module load time, causing stale date in Server/Agent Gateway mode](https://www.chat-gpts.plus/wp-content/uploads/2026/11/21627-91a7a9f0-768x403.jpg)
![[bug]: [v7] Idle invokeai-web pins one CPU core at 100% (7.0.0a2-rocm, Radeon AI PRO R9700)](https://www.chat-gpts.plus/wp-content/uploads/2026/11/9998-ab0c8a13-768x403.jpg)
