MCP 做了一年多的服务端接入最近把客户端从老版的 HTTPSSE 迁移到 Streamable HTTP 时踩了不少坑也把协议文档翻了个底朝天。这个传输层改版其实很多人还没意识到有多重要——它直接决定了你写 MCP Server 时是维护一个端点还是两个端点、要不要自己管 SSE 连接、以及怎么处理那些又长又慢的工具调用。这篇文章就围绕单一端点和按需流式这两个核心设计把我实际迁移和调试过程中的理解、配置和排错记录整理出来希望能帮你少走点弯路。1. 为什么 MCP 要把通信范式改成 Streamable HTTP1.1 旧版 HTTP 传输的问题在哪里在 Streamable HTTP 出现之前MCP 的标准 HTTP 传输方式是HTTPSSE客户端先通过 POST 请求初始化会话服务端返回一个 SSE 端点地址客户端再建立第二个 HTTP 连接去监听服务端的消息。也就是你至少要维护两条连接、两个 URL一个用于请求-响应一个用于服务端推送。这套设计在早期原型里能用但实际接入时问题很明显两个端点的生命周期很难同步。初始化时拿到 SSE 端点地址但一旦网络波动、重连或者负载均衡器介入SSE 连接和 POST 连接各自的超时、重试策略是分开的状态很容易错乱。SSE 连接是常驻的。你哪怕只是发一条 ping也要维持一条 HTTP 长连接开着。在 Serverless 环境比如云函数里长连接几乎是灾难平台几秒不活跃就给你掐断。协议语义割裂。POST 是 JSON-RPCSSE 是纯文本事件流两边都各自实现一遍错误处理、心跳、会话管理代码量直接翻倍。调试困难。两个端点在浏览器 DevTools 和抓包工具里是两套请求排查问题时很难串起来。1.2 Streamable HTTP 的核心设计目标Streamable HTTP 的改版思路本质上就是把两条连接压缩成一条连接、一个端点。它的设计目标很明确单一端点整个服务端只需要暴露一个 URL比如https://api.example.com/mcp客户端的所有操作——不管是发请求、收响应、收服务端推送——都打在这个 URL 上。按需流式客户端通过 POST 发起 JSON-RPC 请求如果响应用不到流式传输就用普通 HTTP JSON 响应直接返回只有当需要推送多个消息或者长时间持续传输时服务端才把响应升级为 SSE 流。流式连接不是常驻的而是按需建立、按需关闭。这样设计解决了三件事第一端点数量从两个变成一个负载均衡和网关配置简单了第二连接的生命周期跟着请求走不再是建立一条永不关闭的 SSEServerless 和普通 Web 服务都能友好支持第三协议语义统一到 HTTP 之上底层还是 JSON-RPC over POSTSSE 只是可选的传输升级。1.3 和 WSS 的关系一种常见的部署补强现在不少 MCP Server 还会额外暴露一个 WSS 端点比如以/mcp为路径、通过 Token 校验的 WebSocket 网关。热词里那些wss://...连接失败的讨论本质上是把 Streamable HTTP 和 WebSocket 传输混在一起考虑时的典型场景。WSS 的价值是双向全双工客户端和服务端可以随时互推消息不需要反复发起 HTTP 请求。但代价是连接管理更复杂、鉴权方式更重、网关层配置更麻烦。我的建议是如果客户端有 WebSocket 基础且需要频繁双向交互可以走 WSS否则优先用 Streamable HTTP因为它在网关、日志、监控、限流上都能直接用现成的 HTTP 中间件运维成本低一个档次。2. 单一端点的本质所有消息都走同一个 URL2.1 单一端点下客户端和服务端的交互流程先看一张我整理的交互流程不用脑补代码先理解流程客户端用POST /mcp发送 JSON-RPC 请求比如initialize。服务端处理请求如果需要流式推送比如工具执行中要发多条进度通知就返回Content-Type: text/event-stream在同一个 HTTP 响应体里按 SSE 格式持续输出消息。如果请求处理完直接有结果比如tools/list服务端返回普通 JSON 响应即可不需要升级成 SSE。客户端在单个响应流结束后如果需要继续发送后续请求重新发起一次 POST。服务端可以通过同一个连接同一响应流主动下发消息但这些消息必须在一个已经建立的 SSE 响应流内完成无法凭空另起一条连接。流程走下来你会发现单一端点不仅仅是 URL 数量上的简化而是整个通信生命周期都集中在同一个 HTTP 语义下。客户端不需要知道什么时候该连 SSE、什么时候该 POST它只需要维护一个 base URL。2.2 协议版本协商initialize 请求怎么处理MCP 协议里客户端和服务端的版本协商发生在initialize请求阶段。Streamable HTTP 在这里有一个特殊设计initialize请求的响应不能是 SSE 流式格式。原因很简单——版本还没协商好双方还不知道对方是否支持流式传输此时如果直接开流兼容性无从谈起。实际操作中服务端在收到initialize时应当返回一个普通的 JSON-RPC 响应并声明自己支持的协议版本、能力包括是否支持流式、是否支持会话恢复。客户端收到响应后再用新的版本号发起后续请求此时服务端才能按 Streamable HTTP 的规则决定是否流式返回。注意如果你在调试时发现initialize响应被切成 SSE 了客户端大概率会直接报streamable http connect failed或解析失败。这属于协议违规不是普通的格式问题。2.3 会话状态与会话恢复单一端点的隐藏机制单一端点模式下客户端和服务端之间可能存在会话状态比如已初始化、授权、上下文缓存。MCP 通过Mcp-Session-Id头来维持这个状态。每次 POST 请求客户端都要带上服务端之前下发的 Session ID服务端根据 Session ID 找到对应的会话上下文。这里有几个容易踩的坑如果服务端不需要会话状态响应里不返回Mcp-Session-Id客户端后续请求也不带这是合法的。如果服务端下发了 Session ID客户端必须在后续请求中带上否则服务端可以把请求当作新会话处理导致工具列表、资源列表全部丢失。会话恢复Session Resumption是可选能力需要服务端在initialize响应里声明sessionManagement相关字段客户端才能决定是否复用会话。我见过不少生产环境的问题都是服务端网关层把Mcp-Session-Id头给吞了或者改写了结果每次请求都像新用户一样。排查这类问题时第一时间查反向代理的头部透传配置。3. 按需流式的核心机制何时升级为 SSE3.1 普通响应和流式响应的判定逻辑按需流式是整个 Streamable HTTP 最关键的语义。服务端必须根据请求内容和自身能力决定返回普通 JSON 还是 SSE 流。判定逻辑一般有三条如果请求是initialize、ping、tools/list、resources/list这类一问一答型请求返回普通 JSON 响应。如果请求是tools/call且工具执行过程中需要推送进度、日志、中间结果或者执行时间很长比如超过网关默认超时服务端应该将响应升级为text/event-stream。如果服务端协议版本较低不支持流式那就必须始终返回普通 JSON不能强行升级。这里有个细节要留意当你把响应升级为 SSE 后客户端会一直保持这个 HTTP 连接开启。客户端的超时设置需要和服务端协商好通常是服务端通过Mcp-Session-Id和心跳注释SSE 的: keep-alive注释行来维持连接活性。3.2 SSE 格式在 MCP 里的具体写法MCP 的 SSE 响应体遵循标准 SSE 格式每一帧包含事件类型和数据字段。在实际抓包中我看到过两种格式事件名message数据是完整的 JSON-RPC 消息。事件名error数据是 JSON-RPC 错误对象表示流内部出错。一个典型的 MCP 流式响应体长这样Content-Type: text/event-stream event: message data: {jsonrpc:2.0,id:1,result:{progress:10,message:开始执行}} event: message data: {jsonrpc:2.0,id:1,result:{progress:50,message:处理中}} event: message data: {jsonrpc:2.0,id:1,result:{progress:100,message:完成,content:[{type:text,text:结果}]}} : keep-alive comment注意几个细节data:后面有时有空格有时没有标准要求必须有一个空格但实际解析中大多数客户端可以容忍无空格格式。每一行必须以换行符结尾空行是 SSE 帧的分隔符。注释行:开头不会触发事件只用来维持连接防止网关空闲超时掐断。3.3 按需流式和传统 SSE 推送的区别很多人容易把 Streamable HTTP 的 SSE 和传统 SSE 搞混。传统 SSE 是服务端主动推送通道一旦建立服务端随时可以发数据客户端不用反复请求。但 Streamable HTTP 的 SSE 是请求-响应流——它必须在一次 POST 请求的响应周期内存在服务端不能在一个响应结束后再用这条流给客户端主动推送新请求的结果。换句话说按需流式是一次性的响应结束就是结束。如果服务端后续想推送新的通知必须等待客户端发起下一次 POST然后在该响应的流中带上。这个语义差异是很多服务端实现出 bug 的重灾区——有人直接套用传统 SSE 的写法在响应结束后继续往流里写数据客户端根本收不到或者直接报错。3.4 长任务执行时的流式缓冲策略工具调用如果涉及长时间执行比如构建镜像、跑测试、爬取网页流式响应需要合理设置缓冲策略。我在 Go 和 Python 服务端里用的方案不太一样Go net/http默认http.ResponseWriter会对小响应自动缓冲。为了流式输出需要设置http.Flusher接口每写入一帧就调用Flush()确保数据及时到客户端而不是攒在缓冲区里。Python FastAPI用StreamingResponse在生成器里 yield SSE 格式字符串不要用JSONResponse去包 SSE 数据。缓冲策略的核心是写一帧、flush 一帧。如果不手动 flush网关可能一直等缓冲区满后才发送客户端会表现为长时间无响应超时后直接报streamable http error: error posting to endpoint。4. 实操我是怎么把 MCP Server 改成 Streamable HTTP 的4.1 服务端改造从两个端点收敛到一个端点我这边原本的服务端代码是用 Python FastAPI 写的暴露了两个端点/mcp处理 POST JSON-RPC/mcp/sse处理 SSE。改造的第一步是把两个端点合并成/mcp根据请求头Accept: text/event-stream判断是否流式返回。伪代码如下app.post(/mcp) async def mcp_endpoint(request: Request): # 解析 JSON-RPC body await request.json() method body.get(method) # 初始化请求不流式返回 if method initialize: return handle_initialize(body) # 工具调用可能需要流式 if method tools/call: # 判断客户端是否接受 SSE accept request.headers.get(accept, ) if text/event-stream in accept and tool_requires_streaming(body): return StreamingResponse(generate_tool_events(body)) # 默认返回普通 JSON return handle_jsonrpc(body)注意这里的tool_requires_streaming是我实践中的折中方案不是所有tools/call都要流式只有那些耗时超过 3 秒或需要推送进度的工具才升级为流式。否则每次调用都建 SSE 流日志里全是连接建立断开的噪音。4.2 客户端接入以 Claude Code 和 Trae IDE 为例客户端接入 Streamable HTTP 比较简单通用的 MCP 客户端都能配。以 Claude Code CLI 为例配置一个远程 MCP Serverclaude mcp add --transport http --url https://api.example.com/mcp my-toolsTrae IDE 里通常在 MCP 配置面板新增远程服务填入 URL 和可选的 Header比如鉴权 Token。热词里提到的谷歌浏览器扩展设置中启用 MCP 连接其实也是同一套逻辑——扩展内部集成了 MCP 客户端配置一个 HTTP URL 即可。我在多个 IDE 客户端里配置时发现一个通用规律只要服务端实现了标准 Streamable HTTP客户端就只需要知道一个 URL 和一个鉴权 Headers。不同客户端的差异主要在配置界面上不在协议上。提示鉴权信息通常放在Authorization或自定义 Header如X-API-Key里。热词里出现的?token...这类 URL 参数形式虽然也有服务端支持但我不推荐——Token 会进访问日志、代理日志泄露风险高得多。4.3 网关配置超时、缓冲和头部透传Streamable HTTP 投入生产后网关Nginx、Kong、Cloudflare 等的配置直接决定稳定性。我整理了一份我的 Nginx 配置片段location /mcp { proxy_pass http://mcp-backend; proxy_http_version 1.1; proxy_set_header Connection ; proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; proxy_send_timeout 300s; }几个关键点proxy_buffering off必须开否则 Nginx 会等后端响应全部积攒完才开始往客户端传流式就失效了。proxy_read_timeout要调大适配长任务执行。如果后端有 SSE 注释心跳proxy_set_header Connection 可以避免 Nginx 强制关闭连接。proxy_request_buffering off这行我建议也加上避免 POST 大请求体时产生额外延迟。4.4 日志和监控怎么跟进热词里有人问MCP server端的日志如何使用自定义日志管理这个问题其实和普通 Web 服务一致只要你的 MCP Server 是基于 HTTP 框架写的直接用框架的日志中间件即可。Streamable HTTP 场景下我关注三个维度连接生命周期每次 POST 的开始、结束、耗时、是否升级为 SSE。会话状态Session ID、初始化时间、最后活跃时间方便排查会话泄漏。错误码分布协议错误、鉴权失败、超时、资源不存在四类错误分开统计。这套日志在排查客户端报连接失败但服务端看起来正常这种问题时特别有用——你会看到请求根本没到服务端问题出在网关或客户端。5. 常见错误和排查记录照着抄就行5.1streamable http connect failed与error posting to endpoint这是热词里出现最多的报错。它有两层含义一是 MCP 客户端发起初始化请求时连接建立失败二是请求已经发出去但服务端返回了非预期响应。我的排查路径是固定的先用 curl 或httpx直接 POST 一个initialize请求到服务端绕过客户端看响应是否符合 MCP 规范。检查服务端initialize响应是否包含正确的协议版本字段protocolVersion。检查鉴权 Header 是否被网关正确透传是否被吞掉。如果请求能到达服务端但响应超时重点查流式响应的 flush 和网关缓冲配置。最经典的一次问题是服务端用的老版本 SDK 返回的协议版本和客户端不兼容客户端拿着旧版本去协商服务端不认直接报错。解决方案简单粗暴——把服务端 SDK 升到支持最新协议版本的版本。5.2 热词里常见的WSS 连接失败到底是什么情况热词里高频出现wss://api.xiaozhi.me/mcp/?token...这类连接失败的讨论。从现象上看这通常是 WebSocket 传输模式下的握手失败。但结合热词里其他内容很多用户其实是把 Streamable HTTP 的 URL 填到了 WebSocket 连接器里或者反过来。我建议这样判断你的客户端如果写的是http://或https://那就是用 Streamable HTTP走 POST 可选 SSE如果写的是ws://或wss://那就是用 WebSocket 传输走全双工。两者不是同一个东西URL 混用必然报连接失败。如果服务端两种传输都支持它应该分别暴露不同路径或通过Upgrade头决定走哪种协议。5.3 排查工具和有效技巧我调试 MCP 通信时最常用的工具组合curl 手测最直观能看到原始请求响应头适合排查鉴权和内容类型问题。浏览器 DevTools如果客户端是浏览器扩展直接在 Network 面板看 POST 请求和 SSE 事件流能看到每个事件的时间线。Burp Suite / Yakit 等代理工具拦截 MCP 请求做改包测试验证服务端对畸形请求的处理。服务端 debug 日志每次请求记录 method、params、耗时、响应状态必要时开启请求体打印。经验如果你在协议栈的各层都已经排查过但仍找不出问题试着换个客户端测同一个服务端。如果别的客户端能连上问题大概率在客户端配置或版本如果别的客户端也连不上问题就在服务端或网关。5.4 兼容性速查表最后放一张我在团队内部传阅的速查表覆盖 Streamable HTTP 最关键协议的该不该、能不能场景是否正确说明initialize 响应用 SSE 流式错误版本协商阶段绝不能开流tools/call 耗时超过 5 秒建议 SSE避免网关超时可推送进度tools/list 响应用 SSE不推荐一次返回完的内容浪费流开销服务端在响应结束后继续写流错误响应结束连接即关闭写不进去客户端每次请求都带 Session ID推荐服务端声明了会话管理时必带网关对 /mcp 开启 buffering错误流式帧会被攒住客户端超时排查时对着这张表过一遍多数问题能快速定位到具体环节。6. 我在实际接入中的几个体会Streamable HTTP 这个范式改得挺聪明它没有引入新协议只是把 HTTP 语义用得更到位了。真正写代码的时候你会发现服务端其实不太关心这是不是 MCP——它就是处理 POST JSON、按需决定要不要转 SSE、管好 Session ID。这让你可以复用大量 Web 服务的最佳实践限流、熔断、鉴权、监控全都现成。我踩过的坑里最值得分享的一条是别在服务端自作主张把所有 POST 都变 SSE。看起来统一用流式很优雅但会让客户端和服务端双方都付出不必要的开销而且很多客户端对非预期 SSE 响应的处理并不完善反而会莫名其妙的报错。另一个体会是协议版本和会话管理这种看不见的能力协商才是真正决定长跑稳定性的东西。很多人调通了初始连接上线后才发现会话丢失、推送错乱回头查都是initialize阶段的能力声明没填对。如果你正在做 MCP Server 接入或者客户端适配建议先把 Streamable HTTP 协议面文档里关于端点、会话、SSE 格式的三张图吃透然后照着这篇文章的流程搭一个最小实验环境跑通 initialize、tools/list、tools/call 三条链路。动手跑一遍比读十遍文档都管用。 
长河君 · 2026/9/30 12:46:07 · 阅读 1.2k MCP Streamable HTTP 实践：单一端点与按需流式避坑指南
MCP 做了一年多的服务端接入最近把客户端从老版的 HTTPSSE 迁移到 Streamable HTTP 时踩了不少坑也把协议文档翻了个底朝天。这个传输层改版其实很多人还没意识到有多重要——它直接决定了你写 MCP Server 时是维护一个端点还是两个端点、要不要自己管 SSE 连接、以及怎么处理那些又长又慢的工具调用。这篇文章就围绕单一端点和按需流式这两个核心设计把我实际迁移和调试过程中的理解、配置和排错记录整理出来希望能帮你少走点弯路。1. 为什么 MCP 要把通信范式改成 Streamable HTTP1.1 旧版 HTTP 传输的问题在哪里在 Streamable HTTP 出现之前MCP 的标准 HTTP 传输方式是HTTPSSE客户端先通过 POST 请求初始化会话服务端返回一个 SSE 端点地址客户端再建立第二个 HTTP 连接去监听服务端的消息。也就是你至少要维护两条连接、两个 URL一个用于请求-响应一个用于服务端推送。这套设计在早期原型里能用但实际接入时问题很明显两个端点的生命周期很难同步。初始化时拿到 SSE 端点地址但一旦网络波动、重连或者负载均衡器介入SSE 连接和 POST 连接各自的超时、重试策略是分开的状态很容易错乱。SSE 连接是常驻的。你哪怕只是发一条 ping也要维持一条 HTTP 长连接开着。在 Serverless 环境比如云函数里长连接几乎是灾难平台几秒不活跃就给你掐断。协议语义割裂。POST 是 JSON-RPCSSE 是纯文本事件流两边都各自实现一遍错误处理、心跳、会话管理代码量直接翻倍。调试困难。两个端点在浏览器 DevTools 和抓包工具里是两套请求排查问题时很难串起来。1.2 Streamable HTTP 的核心设计目标Streamable HTTP 的改版思路本质上就是把两条连接压缩成一条连接、一个端点。它的设计目标很明确单一端点整个服务端只需要暴露一个 URL比如https://api.example.com/mcp客户端的所有操作——不管是发请求、收响应、收服务端推送——都打在这个 URL 上。按需流式客户端通过 POST 发起 JSON-RPC 请求如果响应用不到流式传输就用普通 HTTP JSON 响应直接返回只有当需要推送多个消息或者长时间持续传输时服务端才把响应升级为 SSE 流。流式连接不是常驻的而是按需建立、按需关闭。这样设计解决了三件事第一端点数量从两个变成一个负载均衡和网关配置简单了第二连接的生命周期跟着请求走不再是建立一条永不关闭的 SSEServerless 和普通 Web 服务都能友好支持第三协议语义统一到 HTTP 之上底层还是 JSON-RPC over POSTSSE 只是可选的传输升级。1.3 和 WSS 的关系一种常见的部署补强现在不少 MCP Server 还会额外暴露一个 WSS 端点比如以/mcp为路径、通过 Token 校验的 WebSocket 网关。热词里那些wss://...连接失败的讨论本质上是把 Streamable HTTP 和 WebSocket 传输混在一起考虑时的典型场景。WSS 的价值是双向全双工客户端和服务端可以随时互推消息不需要反复发起 HTTP 请求。但代价是连接管理更复杂、鉴权方式更重、网关层配置更麻烦。我的建议是如果客户端有 WebSocket 基础且需要频繁双向交互可以走 WSS否则优先用 Streamable HTTP因为它在网关、日志、监控、限流上都能直接用现成的 HTTP 中间件运维成本低一个档次。2. 单一端点的本质所有消息都走同一个 URL2.1 单一端点下客户端和服务端的交互流程先看一张我整理的交互流程不用脑补代码先理解流程客户端用POST /mcp发送 JSON-RPC 请求比如initialize。服务端处理请求如果需要流式推送比如工具执行中要发多条进度通知就返回Content-Type: text/event-stream在同一个 HTTP 响应体里按 SSE 格式持续输出消息。如果请求处理完直接有结果比如tools/list服务端返回普通 JSON 响应即可不需要升级成 SSE。客户端在单个响应流结束后如果需要继续发送后续请求重新发起一次 POST。服务端可以通过同一个连接同一响应流主动下发消息但这些消息必须在一个已经建立的 SSE 响应流内完成无法凭空另起一条连接。流程走下来你会发现单一端点不仅仅是 URL 数量上的简化而是整个通信生命周期都集中在同一个 HTTP 语义下。客户端不需要知道什么时候该连 SSE、什么时候该 POST它只需要维护一个 base URL。2.2 协议版本协商initialize 请求怎么处理MCP 协议里客户端和服务端的版本协商发生在initialize请求阶段。Streamable HTTP 在这里有一个特殊设计initialize请求的响应不能是 SSE 流式格式。原因很简单——版本还没协商好双方还不知道对方是否支持流式传输此时如果直接开流兼容性无从谈起。实际操作中服务端在收到initialize时应当返回一个普通的 JSON-RPC 响应并声明自己支持的协议版本、能力包括是否支持流式、是否支持会话恢复。客户端收到响应后再用新的版本号发起后续请求此时服务端才能按 Streamable HTTP 的规则决定是否流式返回。注意如果你在调试时发现initialize响应被切成 SSE 了客户端大概率会直接报streamable http connect failed或解析失败。这属于协议违规不是普通的格式问题。2.3 会话状态与会话恢复单一端点的隐藏机制单一端点模式下客户端和服务端之间可能存在会话状态比如已初始化、授权、上下文缓存。MCP 通过Mcp-Session-Id头来维持这个状态。每次 POST 请求客户端都要带上服务端之前下发的 Session ID服务端根据 Session ID 找到对应的会话上下文。这里有几个容易踩的坑如果服务端不需要会话状态响应里不返回Mcp-Session-Id客户端后续请求也不带这是合法的。如果服务端下发了 Session ID客户端必须在后续请求中带上否则服务端可以把请求当作新会话处理导致工具列表、资源列表全部丢失。会话恢复Session Resumption是可选能力需要服务端在initialize响应里声明sessionManagement相关字段客户端才能决定是否复用会话。我见过不少生产环境的问题都是服务端网关层把Mcp-Session-Id头给吞了或者改写了结果每次请求都像新用户一样。排查这类问题时第一时间查反向代理的头部透传配置。3. 按需流式的核心机制何时升级为 SSE3.1 普通响应和流式响应的判定逻辑按需流式是整个 Streamable HTTP 最关键的语义。服务端必须根据请求内容和自身能力决定返回普通 JSON 还是 SSE 流。判定逻辑一般有三条如果请求是initialize、ping、tools/list、resources/list这类一问一答型请求返回普通 JSON 响应。如果请求是tools/call且工具执行过程中需要推送进度、日志、中间结果或者执行时间很长比如超过网关默认超时服务端应该将响应升级为text/event-stream。如果服务端协议版本较低不支持流式那就必须始终返回普通 JSON不能强行升级。这里有个细节要留意当你把响应升级为 SSE 后客户端会一直保持这个 HTTP 连接开启。客户端的超时设置需要和服务端协商好通常是服务端通过Mcp-Session-Id和心跳注释SSE 的: keep-alive注释行来维持连接活性。3.2 SSE 格式在 MCP 里的具体写法MCP 的 SSE 响应体遵循标准 SSE 格式每一帧包含事件类型和数据字段。在实际抓包中我看到过两种格式事件名message数据是完整的 JSON-RPC 消息。事件名error数据是 JSON-RPC 错误对象表示流内部出错。一个典型的 MCP 流式响应体长这样Content-Type: text/event-stream event: message data: {jsonrpc:2.0,id:1,result:{progress:10,message:开始执行}} event: message data: {jsonrpc:2.0,id:1,result:{progress:50,message:处理中}} event: message data: {jsonrpc:2.0,id:1,result:{progress:100,message:完成,content:[{type:text,text:结果}]}} : keep-alive comment注意几个细节data:后面有时有空格有时没有标准要求必须有一个空格但实际解析中大多数客户端可以容忍无空格格式。每一行必须以换行符结尾空行是 SSE 帧的分隔符。注释行:开头不会触发事件只用来维持连接防止网关空闲超时掐断。3.3 按需流式和传统 SSE 推送的区别很多人容易把 Streamable HTTP 的 SSE 和传统 SSE 搞混。传统 SSE 是服务端主动推送通道一旦建立服务端随时可以发数据客户端不用反复请求。但 Streamable HTTP 的 SSE 是请求-响应流——它必须在一次 POST 请求的响应周期内存在服务端不能在一个响应结束后再用这条流给客户端主动推送新请求的结果。换句话说按需流式是一次性的响应结束就是结束。如果服务端后续想推送新的通知必须等待客户端发起下一次 POST然后在该响应的流中带上。这个语义差异是很多服务端实现出 bug 的重灾区——有人直接套用传统 SSE 的写法在响应结束后继续往流里写数据客户端根本收不到或者直接报错。3.4 长任务执行时的流式缓冲策略工具调用如果涉及长时间执行比如构建镜像、跑测试、爬取网页流式响应需要合理设置缓冲策略。我在 Go 和 Python 服务端里用的方案不太一样Go net/http默认http.ResponseWriter会对小响应自动缓冲。为了流式输出需要设置http.Flusher接口每写入一帧就调用Flush()确保数据及时到客户端而不是攒在缓冲区里。Python FastAPI用StreamingResponse在生成器里 yield SSE 格式字符串不要用JSONResponse去包 SSE 数据。缓冲策略的核心是写一帧、flush 一帧。如果不手动 flush网关可能一直等缓冲区满后才发送客户端会表现为长时间无响应超时后直接报streamable http error: error posting to endpoint。4. 实操我是怎么把 MCP Server 改成 Streamable HTTP 的4.1 服务端改造从两个端点收敛到一个端点我这边原本的服务端代码是用 Python FastAPI 写的暴露了两个端点/mcp处理 POST JSON-RPC/mcp/sse处理 SSE。改造的第一步是把两个端点合并成/mcp根据请求头Accept: text/event-stream判断是否流式返回。伪代码如下app.post(/mcp) async def mcp_endpoint(request: Request): # 解析 JSON-RPC body await request.json() method body.get(method) # 初始化请求不流式返回 if method initialize: return handle_initialize(body) # 工具调用可能需要流式 if method tools/call: # 判断客户端是否接受 SSE accept request.headers.get(accept, ) if text/event-stream in accept and tool_requires_streaming(body): return StreamingResponse(generate_tool_events(body)) # 默认返回普通 JSON return handle_jsonrpc(body)注意这里的tool_requires_streaming是我实践中的折中方案不是所有tools/call都要流式只有那些耗时超过 3 秒或需要推送进度的工具才升级为流式。否则每次调用都建 SSE 流日志里全是连接建立断开的噪音。4.2 客户端接入以 Claude Code 和 Trae IDE 为例客户端接入 Streamable HTTP 比较简单通用的 MCP 客户端都能配。以 Claude Code CLI 为例配置一个远程 MCP Serverclaude mcp add --transport http --url https://api.example.com/mcp my-toolsTrae IDE 里通常在 MCP 配置面板新增远程服务填入 URL 和可选的 Header比如鉴权 Token。热词里提到的谷歌浏览器扩展设置中启用 MCP 连接其实也是同一套逻辑——扩展内部集成了 MCP 客户端配置一个 HTTP URL 即可。我在多个 IDE 客户端里配置时发现一个通用规律只要服务端实现了标准 Streamable HTTP客户端就只需要知道一个 URL 和一个鉴权 Headers。不同客户端的差异主要在配置界面上不在协议上。提示鉴权信息通常放在Authorization或自定义 Header如X-API-Key里。热词里出现的?token...这类 URL 参数形式虽然也有服务端支持但我不推荐——Token 会进访问日志、代理日志泄露风险高得多。4.3 网关配置超时、缓冲和头部透传Streamable HTTP 投入生产后网关Nginx、Kong、Cloudflare 等的配置直接决定稳定性。我整理了一份我的 Nginx 配置片段location /mcp { proxy_pass http://mcp-backend; proxy_http_version 1.1; proxy_set_header Connection ; proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; proxy_send_timeout 300s; }几个关键点proxy_buffering off必须开否则 Nginx 会等后端响应全部积攒完才开始往客户端传流式就失效了。proxy_read_timeout要调大适配长任务执行。如果后端有 SSE 注释心跳proxy_set_header Connection 可以避免 Nginx 强制关闭连接。proxy_request_buffering off这行我建议也加上避免 POST 大请求体时产生额外延迟。4.4 日志和监控怎么跟进热词里有人问MCP server端的日志如何使用自定义日志管理这个问题其实和普通 Web 服务一致只要你的 MCP Server 是基于 HTTP 框架写的直接用框架的日志中间件即可。Streamable HTTP 场景下我关注三个维度连接生命周期每次 POST 的开始、结束、耗时、是否升级为 SSE。会话状态Session ID、初始化时间、最后活跃时间方便排查会话泄漏。错误码分布协议错误、鉴权失败、超时、资源不存在四类错误分开统计。这套日志在排查客户端报连接失败但服务端看起来正常这种问题时特别有用——你会看到请求根本没到服务端问题出在网关或客户端。5. 常见错误和排查记录照着抄就行5.1streamable http connect failed与error posting to endpoint这是热词里出现最多的报错。它有两层含义一是 MCP 客户端发起初始化请求时连接建立失败二是请求已经发出去但服务端返回了非预期响应。我的排查路径是固定的先用 curl 或httpx直接 POST 一个initialize请求到服务端绕过客户端看响应是否符合 MCP 规范。检查服务端initialize响应是否包含正确的协议版本字段protocolVersion。检查鉴权 Header 是否被网关正确透传是否被吞掉。如果请求能到达服务端但响应超时重点查流式响应的 flush 和网关缓冲配置。最经典的一次问题是服务端用的老版本 SDK 返回的协议版本和客户端不兼容客户端拿着旧版本去协商服务端不认直接报错。解决方案简单粗暴——把服务端 SDK 升到支持最新协议版本的版本。5.2 热词里常见的WSS 连接失败到底是什么情况热词里高频出现wss://api.xiaozhi.me/mcp/?token...这类连接失败的讨论。从现象上看这通常是 WebSocket 传输模式下的握手失败。但结合热词里其他内容很多用户其实是把 Streamable HTTP 的 URL 填到了 WebSocket 连接器里或者反过来。我建议这样判断你的客户端如果写的是http://或https://那就是用 Streamable HTTP走 POST 可选 SSE如果写的是ws://或wss://那就是用 WebSocket 传输走全双工。两者不是同一个东西URL 混用必然报连接失败。如果服务端两种传输都支持它应该分别暴露不同路径或通过Upgrade头决定走哪种协议。5.3 排查工具和有效技巧我调试 MCP 通信时最常用的工具组合curl 手测最直观能看到原始请求响应头适合排查鉴权和内容类型问题。浏览器 DevTools如果客户端是浏览器扩展直接在 Network 面板看 POST 请求和 SSE 事件流能看到每个事件的时间线。Burp Suite / Yakit 等代理工具拦截 MCP 请求做改包测试验证服务端对畸形请求的处理。服务端 debug 日志每次请求记录 method、params、耗时、响应状态必要时开启请求体打印。经验如果你在协议栈的各层都已经排查过但仍找不出问题试着换个客户端测同一个服务端。如果别的客户端能连上问题大概率在客户端配置或版本如果别的客户端也连不上问题就在服务端或网关。5.4 兼容性速查表最后放一张我在团队内部传阅的速查表覆盖 Streamable HTTP 最关键协议的该不该、能不能场景是否正确说明initialize 响应用 SSE 流式错误版本协商阶段绝不能开流tools/call 耗时超过 5 秒建议 SSE避免网关超时可推送进度tools/list 响应用 SSE不推荐一次返回完的内容浪费流开销服务端在响应结束后继续写流错误响应结束连接即关闭写不进去客户端每次请求都带 Session ID推荐服务端声明了会话管理时必带网关对 /mcp 开启 buffering错误流式帧会被攒住客户端超时排查时对着这张表过一遍多数问题能快速定位到具体环节。6. 我在实际接入中的几个体会Streamable HTTP 这个范式改得挺聪明它没有引入新协议只是把 HTTP 语义用得更到位了。真正写代码的时候你会发现服务端其实不太关心这是不是 MCP——它就是处理 POST JSON、按需决定要不要转 SSE、管好 Session ID。这让你可以复用大量 Web 服务的最佳实践限流、熔断、鉴权、监控全都现成。我踩过的坑里最值得分享的一条是别在服务端自作主张把所有 POST 都变 SSE。看起来统一用流式很优雅但会让客户端和服务端双方都付出不必要的开销而且很多客户端对非预期 SSE 响应的处理并不完善反而会莫名其妙的报错。另一个体会是协议版本和会话管理这种看不见的能力协商才是真正决定长跑稳定性的东西。很多人调通了初始连接上线后才发现会话丢失、推送错乱回头查都是initialize阶段的能力声明没填对。如果你正在做 MCP Server 接入或者客户端适配建议先把 Streamable HTTP 协议面文档里关于端点、会话、SSE 格式的三张图吃透然后照着这篇文章的流程搭一个最小实验环境跑通 initialize、tools/list、tools/call 三条链路。动手跑一遍比读十遍文档都管用。