快速结论:在使用 FastMCP 的流式 HTTP 传输(stateless_http=True)时,Context.report_progress() 发出的进度通知无法通过 SSE 送达客户端。优先排查 SDK 版本是否为 1.28.1 或更低,并检查 send_progress_notification() 调用是否缺少 related_request_id 参数。
适用环境:MCP Python SDK 1.26.0 ~ 1.28.1(未包含 #2994 修复的版本),Python 3.11,使用 Streamable HTTP 传输并设置 stateless_http=True。
最快修复方案:若无法立即升级到包含修复的版本(v2 或等待 1.x 后续补丁),可用以下 workaround 替代 ctx.report_progress():
progress_token = ctx.request_context.meta.progressToken if ctx.request_context.meta else None
if progress_token is not None:
await ctx.session.send_progress_notification(
progress_token=progress_token,
progress=progress,
total=total,
message=message,
related_request_id=ctx.request_id,
)
注意事项:该 workaround 需手动处理 progress_token 和 related_request_id,使用前请确认 ctx.request_id 可用。后续官方修复发布后应移除此冗余代码。
问题场景
用户在 FastMCP 服务器中启用 stateless_http=True(Streamable HTTP 传输),并在工具函数中调用 ctx.report_progress(progress, total, message) 来报告进度。客户端通过 SSE 监听进度通知,但始终收不到任何进度事件;而 ctx.info() 等日志消息可以正常送达。
报错原文
Progress notifications not delivered via SSE in stateless HTTP mode
(客户端无明显的 Python 异常输出,仅表现为进度回调从未触发。)
原因分析
在 Context.report_progress() 的实现中(位于 src/mcp/server/fastmcp/server.py),调用 send_progress_notification() 时缺少 related_request_id 参数。SSE 传输依赖该字段将通知路由到正确的客户端请求;缺少时,通知会被静默丢弃。相对的,Context.info() 等日志方法正确
参考来源
modelcontextprotocol/python-sdk #2001
AI 工具推荐
想把多个 AI 模型放在一个入口?
GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。
推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。
这个方案解决了吗?
可以继续搜索完整报错,或查看同一工具的其他排查指南。


![[Question]: [MinerU] Output directory](https://www.chat-gpts.plus/wp-content/uploads/2026/07/11691-e87e0a36-768x403.jpg)