Progress notifications not delivered via SSE in stateless HTTP mode

在使用 FastMCP 的流式 HTTP 传输( stateless_http=True )时, Context.report_progress() 发出的进度通知无法通过 SSE 送达客户端。优先排查 SDK 版本是否为 1.28.1 或更低,并检查 send_progress_notificat

快速结论:在使用 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_tokenrelated_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

GamsGo AI

AI 工具推荐

想把多个 AI 模型放在一个入口?

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 15798

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注