最近在折腾 MCPModel Context Protocol远程服务的时候我发现很多人还在按旧的 HTTPSSE 方案写代码两个端点来回配流还动不动断。实际上MCP 规范早就把默认远程传输方式升级成了 Streamable HTTP核心就八个字单一端点、按需流式。这篇文章就围绕这两个关键词展开从协议设计讲到代码实现最后附上我在实际调试中反复踩过的坑适合正在做 MCP server 开发、或者想把 Claude Desktop / Cursor / Trae 这类工具接上自建服务的同学。1. Streamable HTTP 改了什么从两个 URL 到一个 URL1.1 旧版 HTTPSSE 到底哪里不爽在展开新方案之前先回顾一下 MCP 远程传输的演进。MCP 从诞生起就分了两条路本地进程之间用 stdio走标准输入输出远程服务则最早采用 HTTPSSE 组合。所谓 HTTPSSE实际上把传输拆成了两个端点。服务端要同时暴露两个 URL一个是 SSE 端点专门给客户端建立一条服务器到客户端的长连接服务器有任何主动消息都通过这条 SSE 流推下去另一个是消息端点客户端把 JSON-RPC 请求 POST 到这里。问题也由此而来客户端必须先连 SSE再访问消息端点只要 SSE 断了整个会话状态就得重新初始化。部署时还得处理两条路各自的安全策略、跨域规则和超时配置稍微一多就乱。这还不是最头疼的。SSE 连接本身是长期占用的客户端哪怕没有服务器推送需求也得维持这条连接定时收 ping 或者 heartbeat。放到 Kubernetes 这类动态环境里一条常驻连接会让负载均衡和滚动发布的处理变得很别扭缩容、重启都会把连接掐断客户端必须设计一整套重连逻辑否则服务一发布所有在线客户端集体掉线。1.2 新传输的三个核心变化Streamable HTTP 的出现本质上是把“连接”这件事从协议里拆了出来。它保留了底层 HTTP 的语义又把面向消息的交互统一到一个端点上。相比旧方案有三个关键变化值得注意。第一是端点收敛。服务端只需要暴露一个 URLPOST 和 GET 都打在这个地址上。客户端配置里只需要填一个 url 字段不用再记住 /sse 和 /messages 两套路径。这看起来只是配置简化实际影响很大反向代理、网关授权、负载均衡策略都只要针对一个路径配置排查网络问题时的变量也少了一半。第二是“按需流式”。服务器收到 POST 请求后不再默认必须开一条 SSE 流。简单请求比如 initialize、tools/list直接一次性返回完整 JSON 就结束了只有长耗时的操作比如 tools/call 要执行一个需要几秒甚至更久的任务服务端才选择用 text/event-stream 分块推结果。这就是按需的含义流式不是默认姿态而是服务器根据响应特性临时决定的响应格式。第三是会话和连接解耦。旧方案里 SSE 连接几乎等同于会话断了就丢。新方案引入 MCP-Session-Id 头字段会话状态绑定在 ID 上而不是绑定在某一条物理连接上。连接断了不要紧只要会话还在客户端重新发起请求并带上同一个 ID 即可继续。这个设计让断线恢复变得轻量也更贴近普通 HTTP 服务的使用习惯。1.3 传输方式与协议版本的关系这里顺手回答一个被问了很多次的问题MCP 到底是软件协议还是硬件协议该归到哪一层MCP 是一个应用层协议消息格式基于 JSON-RPC 2.0传输层可以走 stdio也可以走 HTTP。它跟 TCP 不在一个层次TCP 是传输控制协议HTTP 构建在 TCP 之上MCP 又构建在 HTTP 之上。类比一下MCP 之于 AI 应用有点像 SQL 之于数据库是一套“客户端和服务端之间怎么对话”的约定不是物理层面的东西。在实现时要注意Streamable HTTP 是随协议版本演进的。早期 MCP 版本2024-11-05 那一代只有 HTTPSSE后来规范引入了 Streamable HTTP并逐步成为推荐方式协议版本号也更新到了 2025-03-26 以及后续的 2025-06-18。客户端初始化时会带上自己支持的 protocolVersion服务端如果支持就返回相同版本如果不支持则要通知客户端降级或拒绝。所以遇到“版本协商”相关的报错先看两边的 SDK 版本是否够新很多莫名其妙的兼容问题其实是旧版本 SDK 还在用旧传输方式。2. 拆解“单一端点 按需流式”的工作原理2.1 一个端点如何承载所有 JSON-RPC 消息单一端点的实现思路并不神秘。所有发往 MCP 服务器的消息initialize、tools/list、tools/call、notifications/initialized都做 HTTP POST消息体就是标准的 JSON-RPC 2.0 格式。服务器根据 method 分发处理这在路由层面只需要一个接口。但端点统一不代表逻辑简单。为了理解协议全貌可以先记住 JSON-RPC 层的三种消息形态消息类型作用典型 method请求客户端或服务端发出要求对方响应initialize、tools/list、tools/call响应对请求的应答携带 result 或 error与请求 id 对应通知单向消息不需要任何应答notifications/initialized服务端在处理 POST 请求时要能区分这三种情况。普通请求要返回结果通知不需要返回部分请求需要保持连接、以流式方式逐步返回。如何从请求头区分客户端一般会在 POST 请求里带上 Accept: application/json, text/event-stream表示“两种响应格式我都接受”。服务端根据业务场景自己决定能算完就回 JSON要长时间执行就走 SSE。客户端则必须同时兼容这两种形态否则很可能连接正常却读不到数据。这个取舍很符合 HTTP 生态的直觉。开发者不需要为了“流式”这个能力付出常驻连接的代价也不需要为了实现流式而另起一套协议。一切还是标准 HTTP有请求有响应响应可以是大块 JSON也可以是分几段传的 JSON 事件流。2.2 按需流式何时返回 JSON何时返回 SSE按需流式的判定标准说白了就是“服务器需要多久才能产出完整结果”。我实际开发中归纳出一个简单的判断列表简单的元数据查询initialize、tools/list、resources/list用一次性 JSON 返回这类请求毫秒级完成开流纯属浪费。中等耗时的操作读取某个固定资源、查单个数据也可以直接 JSON 返回客户端等几秒一般可以接受。真正需要流式的场景是任务式调用比如 tools/call 触发了模型推理、文件处理、批量扫描等无法预知耗时的操作。这时候服务端返回普通 JSON 就不合适了因为客户端没法区分“还在等”和“已经结束了”。在实现流式响应时SSE 帧的格式有讲究。每个事件里 data 字段必须是一个完整的 JSON-RPC 消息可以是响应也可以是服务器主动推送的通知。客户端解析时不能只读一次 data 就完事要持续监听直到流关闭并且要注意区分 event 字段。MCP 规范里定义了几个保留事件名比如 message 代表 JSON-RPC 消息ping 代表心跳。新手最容易犯的错是把 SSE 当成“一次读一大块”的普通响应然后在流未结束时就去 json.loads结果解析报错。正确做法是逐行读 data: 前缀的内容按双换行边界切分事件。提示SSE 流的 data 字段里不能有裸换行JSON 序列化后必须保持单行。如果直接在 data 后面塞多行文本解析端会直接把流拆碎这是自找麻烦。2.3 会话标识MCP-Session-Id 与连接复用工作会话在 Streamable HTTP 里是用 MCP-Session-Id 管理的。流程是这样的客户端第一次 POST initialize 时没有带 session ID服务端处理成功后会在响应头返回一个新建的 MCP-Session-Id客户端必须记下来之后的所有 POST 和 GET 都带上这个值。如果服务端发现请求没带 ID或者 ID 对应的会话已经过期一般会返回 400 或 404客户端此时只能重新初始化。这个机制的正面意义是连接复用变得安全。HTTP 连接本身是不保存状态的客户端 SDK 底层用连接池保持 TCP 连接复用但“会话”是应用层概念靠 header 串联。某个请求执行到一半连接断了客户端可以立刻重建连接带着同一个 MCP-Session-Id 继续发下一个请求不需要把所有工具列表、能力配置重新握手一遍。这在旧方案里做不到旧方案一旦 SSE 断线基本等于要从 initialize 重新开始。我见过一些人在 FastAPI 里写 handler 时忘了从响应头里取出 session id后续请求自然带不上于是反复收到 400排查半天才发现是代码里丢了值。这种错误非常隐蔽建议把 MCP-Session-Id 的存取放在一个公共拦截器里而不是每个请求手动处理。2.4 GET 请求与流恢复机制POST 只能用于客户端发消息、服务端被动响应。但 MCP 里还有一类场景需求正好相反服务器希望主动向客户端推送消息比如资源内容变化、任务进度通知。这就是 GET 请求的价值所在。客户端可以向同一个端点发 GET 请求服务端返回一条 SSE 流持续推送服务器主动产生的 JSON-RPC 消息。对于大多数只需要“一问一答”的客户端完全可以不发 GET只在发起 POST 调用后用 POST 响应里的 SSE 拿结果GET 流是可选项不是必须的。这也是“按需”二字的另一层含义。需要注意如果客户端和服务端之间有比较严格的网关控制GET 流很容易被网关当作普通请求处理提前关闭连接或者缓冲响应。后面排查章节会细说这里先记住一个原则GET 流只在你需要接收服务端主动消息时才开不要为了“保持在线”而长期挂一条空流这跟旧方案的常驻连接没有区别违背了新范式的设计初衷。新版规范还引入了流恢复resume机制客户端断开后可以用 lastMessageId 告诉服务器“我从某条消息之后继续”服务器把缓存的消息补发。这套机制极大降低了真实网络环境下的消息丢失率但它依赖服务端实现消息持久化不是默认开启的。做生产级 server 时建议支持做 demo 时可以省略。3. 实操从零搭建一个可用的 Streamable HTTP 服务3.1 环境准备与工具链选择先说我推荐的最小工具链Python 3.10官方 MCP Python SDKFastMCP 封装层uvicorn 作服务器。为什么选 Python 这条路因为官方 SDK 对 Streamable HTTP 的支持最完整FastMCP 帮我们省掉了大量 JSON-RPC 路由细节可以直接把注意力放在业务上。如果你更习惯 Node.js 生态官方 TypeScript SDK 也支持同样的传输方式原理完全一致。安装命令很简单pip install mcp[cli] uvicorn注意这里要用带引号的 mcp[cli] 安装否则某些 shell 会把方括号当通配符处理。安装后命令行里就有 mcp 命令用它跑 FastMCP 应用非常方便。装完顺手确认一下 SDK 版本。早期版本里 streamable-http 的支持并不完整建议打印一下版本号2025 年 4 月之后的版本基本都稳定了。3.2 最小可用的单端点服务器下面这个例子是一个只提供一个天气查询工具的 MCP server麻雀虽小五脏俱全。from fastmcp import FastMCP mcp FastMCP(demo-weather) mcp.tool() def get_weather(city: str) - str: 查询指定城市的当前天气 if city 北京: return 多云18℃空气质量良 if city 上海: return 阴天22℃空气质量优 return f{city}暂无数据请稍后再试 if __name__ __main__: mcp.run(transportstreamable-http, host127.0.0.1, port8000)保存为 server.py然后运行python server.pyFastMCP 默认会把端点挂到 http://127.0.0.1:8000/mcp/ 这个路径。日志里会输出端点地址和启动信息。走到这一步你的“单一端点”服务就已经在跑了。这段代码做的事很简单注册一个叫 get_weather 的工具函数名、参数、docstring 会被 FastMCP 自动提炼成 JSON SchemaMCP 客户端通过 tools/list 拉到的就是这个工具的“说明书”。然后通过 tools/call 传入参数服务端执行函数并把结果返回。整个过程根本不需要手写 JSON-RPC 解析。3.3 客户端配置的两种姿势有了服务端客户端怎么连最常见的方式是写 MCP 配置文件。Claude Desktop、Cursor、Trae 这类工具都支持在配置里声明 mcpServers指向远程服务时只需要给出 url{ mcpServers: { weather: { url: http://127.0.0.1:8000/mcp/ } } }保存配置文件后重启客户端它就会自动发起 initialize 握手并注册工具。第二种方式是在自己的程序里用官方 SDK 直连。这里用 Python 客户端演示import asyncio from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client async def main(): async with streamablehttp_client(http://127.0.0.1:8000/mcp/) as (read, write, _): async with ClientSession(read, write) as session: tools await session.list_tools() print(可用工具:, [t.name for t in tools]) result await session.call_tool(get_weather, {city: 北京}) print(查询结果:, result) asyncio.run(main())streamablehttp_client 这个上下文管理器负责创建连接、管理会话 ID、处理 SSE 解析和 JSON-RPC 消息路由。用 SDK 的好处是断线重连、会话恢复这些底层逻辑有官方实现兜底不需要自己再造轮子。3.4 看一眼真实请求长什么样为了理解握手细节建议用 curl 或者浏览器开发者工具抓一次请求。我用 Python 客户端跑上面的 demo 时网络面板里能看到这样的结构。初始化请求POST /mcp/ HTTP/1.1 Host: 127.0.0.1:8000 Content-Type: application/json Accept: application/json, text/event-stream {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2025-03-26,capabilities:{},clientInfo:{name:python-client,version:1.0.0}}}服务器首次响应尚未建立会话会在响应头里下发 MCP-Session-IdHTTP/1.1 200 OK Content-Type: application/json MCP-Session-Id: 8f3a2b9c-d5e4-4a1f-9a88-7c2b1d0e4f6a {jsonrpc:2.0,id:1,result:{protocolVersion:2025-03-26,capabilities:{tools:{}},serverInfo:{name:demo-weather,version:0.1.0}}}之后的所有请求都带上这个 IDPOST /mcp/ HTTP/1.1 Content-Type: application/json MCP-Session-Id: 8f3a2b9c-d5e4-4a1f-9a88-7c2b1d0e4f6a Accept: application/json, text/event-stream {jsonrpc:2.0,id:2,method:tools/list,params:{}}如果你调用了一个需要流式返回的工具响应头会变成 Content-Type: text/event-stream响应体是多个空行分隔的 SSE 事件每个事件的 data 字段是一条 JSON-RPC 消息。理解了这三个请求的形态整个单一端点协议你就吃透了八成。4. 常见报错与排查实录4.1 connect failed / error posting to endpoint我在社区里看到最多的报错就是类似“streamable http connect failed: streamable http error: error posting to endpoint”这种。它本质上是客户端在 POST 阶段就失败了可能原因按出现频率排序如下端点路径不对。客户端配置的 url 缺了 /mcp/ 后缀或者服务器把端点挂在了别的路径。用 FastMCP 时一定要确认日志里的实际地址。服务器没起来或者端口没开。最简单的方式是 curl -v 访问端点如果返回 connection refused问题在服务端。协议版本不匹配。客户端 SDK 太新、服务端 SDK 太旧或者反过来双方支持的 protocolVersion 交集为空握手直接失败。解决办法是统一升级两边 SDK。中间网关拦截。公司网络环境常有这个坑代理把自定义 Header比如 MCP-Session-Id过滤掉了导致后续请求变成无会话请求。排查方法遵循“从下往上”原则先确认 TCP 连通性再确认 HTTP 状态码最后看 JSON-RPC 层错误。尽量不要一上来就翻 SDK 源码那样只会浪费时间。4.2 SSE 流中断、超时与代理缓冲自建远程 MCP 服务时流式连接稳定性是最大痛点。常见现象是客户端能连上握手也没问题但一调用长耗时工具响应读了一半就卡住或直接断开。这类问题 90% 出在中间代理或反向代理的缓冲和超时配置。Nginx 默认会对上游响应做缓冲等攒满一定大小才发给客户端SSE 这种逐行推送的响应在缓冲区里一憋就是几分钟客户端自然以为超时。解决办法是关闭该路径的代理缓冲并调大读取超时。如果用的是 Nginx可以参考这样的配置location /mcp/ { proxy_pass http://127.0.0.1:8000; proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; proxy_http_version 1.1; proxy_set_header Connection ; }proxy_set_header Connection 是避免协议升级冲突的常用手段。开启后长耗时的 SSE 响应能稳定跑完。另外提醒一句SSE 是纯文本流不要在服务端手动 gzip 压缩很多 SDK 对压缩后的 SSE 解析并不友好会破坏事件边界。4.3 会话失效与多实例粘滞问题当 MCP server 部署成多副本比如 K8s 里起了 3 个 Pod很容易遇到“同一个会话一会儿好用一会儿 400”的怪问题。原因在于 MCP-Session-Id 默认存在单个实例的内存里客户端第一次请求落在 Pod A第二次被负载均衡器转发到 Pod BPod B 根本不认识这个会话。解决办法有两条路。一是负载均衡层按 MCP-Session-Id 做一致性路由让同一个会话始终打到同一个 Pod也就是粘滞会话二是把会话状态放到 Redis 之类的共享存储里所有实例都能查到。前者简单高效适合中小规模后者是彻底方案但要注意序列化 MCP 会话对象时除了工具注册信息还要保存协议版本、客户端信息等上下文别漏了。会话过期也很常见。很多实现默认会话有效期只有几分钟客户端长时间不活动后首次请求就会收到 404 或 400。这不是 bug是设计如此。客户端 SDK 一般会自动重新 initialize但如果遇到“反复重新握手”的情况就要检查服务端的会话清理策略是不是太激进。4.4 缓存造成的“假执行”还有一个隐蔽坑HTTP 缓存。MCP 端点如果被 CDN 或者网关默认加了缓存策略那么同一个请求可能会被缓存下次调用直接返回上一次的结果造成工具“没执行却返回成功”的假象。对 AI Agent 来说这是非常危险的错误行为因为它污染了模型的观察结果。解决方案是在服务端明确禁止缓存。用 FastAPI 写中间件的话可以这样from fastapi import FastAPI from fastapi.responses import JSONResponse app FastAPI() app.middleware(http) async def no_cache(request, call_next): response await call_next(request) response.headers[Cache-Control] no-store return response同时确保 MCP-Session-Id 这类自定义头不会被网关丢弃。如果网络链路里确实有缓存设备不好控制可以从根上绕开给每个客户端用独立端点或者在请求里加时间戳参数破坏缓存键。但最优雅的做法仍然是服务端统一返回 no-store。最后把这次调试中反复用到的排查思路整理成一张速查表贴在这里备查现象大概率原因首选动作connection refused服务未启动 / 端口错误curl 验证端口连通性400 Bad Request缺失或失效的 MCP-Session-Id检查请求头是否带会话 ID握手后立刻断开协议版本不兼容统一升级两端 SDKSSE 流卡住中断代理缓冲 / 超时关闭 proxy_buffering调大超时同样请求返回旧结果HTTP 缓存服务端返回 Cache-Control: no-store多副本下时好时坏会话未共享 / 路由未粘滞按 session id 做一致性路由我个人在实际操作中的体会是做 MCP server 时不要一上来就纠结底层协议细节先用 SDK 把最小闭环跑通再回头理解单一端点和按需流式的设计你会发现一切都很自然。流式是手段不是目的能够用普通 JSON 返回的请求就不要为了“看起来高级”去开 SSE 流真正需要流式的地方再仔细调代理、调超时、调会话恢复。踩过几次坑之后我现在写 Streamable HTTP 服务基本就是三步走FastMCP 起服务客户端配置连上Nginx 关闭缓冲。剩下的问题绝大多数都能通过对日志和响应头的细致排查找到答案。
