MCP 的三种数据传输模式教程stdio / SSE / Streamable HTTP适用日期2026-03-25术语说明本文的“SSE 模式”指旧版 HTTPSSE 传输legacy不是 Streamable HTTP 中可选的 SSE 流式响应。1. 优先级如果你现在在做新项目优先级应该是本地单机场景stdio远程服务化场景streamable-httpHTTPSSE旧版仅用于兼容历史客户端/服务端原因很简单MCP 最新规范2025-11-25标准传输是stdio streamable-http旧HTTPSSE已被替代保留主要是向后兼容1.1 版本时间线2024-11-05规范里有stdio与旧HTTPSSE传输2025-03-26规范开始将远程 HTTP 方向切到streamable-http2025-11-25streamable-http成为当前主方案旧HTTPSSE进入兼容语义如果你在文档里看到 “SSE transport”先确认是哪个版本的规范不要混在一起解读。2. 三种模式总览对比维度stdioHTTPSSE旧streamable-http新连接形态客户端拉起子进程远程 HTTP 双端点远程 HTTP 单端点标准状态当前标准已废弃兼容当前标准通信方式stdin/stdout 行分隔 JSON-RPCSSE 收消息 POST 发消息POST 发消息响应可 JSON 或 SSE也可 GET 打开 SSE典型部署本机工具、IDE 插件历史系统云服务、网关、多客户端复杂度低中-高中关键风险stdout 混入日志端点管理复杂鉴权、会话、重连3. 模式一stdio3.1 适合什么场景MCP Server 与客户端部署在同一台机器你希望最小化网络、鉴权、反向代理复杂度开发调试阶段先跑通能力3.2 通信模型Client 启动 Server 子进程 Client - (stdin) - Server Server - (stdout) - Client stderr 仅用于日志规范关键点JSON-RPC 消息按“每行一条”分隔消息不能包含内嵌换行stdout只能输出合法 MCP 消息日志写stderr不要写stdout3.3 最小示例配置思路[mcp_servers.my_local_stdio] command python args [/path/to/server.py]3.4 优缺点优点简单、稳定、延迟低不涉及 HTTP 暴露面缺点不能天然做远程多客户端共享进程生命周期由客户端托管运维能力较弱3.5 常见坑Server 把日志打印到stdout导致 JSON-RPC 解析失败某些库输出 banner 到stdout子进程环境变量不完整导致认证失败4. 模式二HTTPSSE旧版legacy这是历史方案常见于老 MCP 客户端。新系统建议迁移到streamable-http。4.1 它是怎么工作的旧模式需要两个端点SSE 端点客户端建立事件流、接收服务端消息POST 端点客户端把 JSON-RPC 发给服务端建立连接后服务端先在 SSE 流发一个endpoint事件告诉客户端“后续 POST 发到哪个 URL”。4.2 典型时序GET /sse (打开 SSE) - event: endpoint data: {uri:/messages?...} POST /messages?... (发送 JSON-RPC) - event: message data: {...JSON-RPC...}4.3 为什么被替代模型简单但端点分裂集成成本高与现代 API 网关和统一路由模型不够一致新规范将远程通信统一到streamable-http4.4 什么时候还会用到你的客户端仍停留在老协议栈你在做历史系统迁移期双栈兼容5. 模式三streamable-http推荐5.1 核心特征使用一个 MCP endpoint如/mcp该端点必须支持POST可选支持GETPOST发送 JSON-RPC响应可为application/json单次返回text/event-streamSSE 流式返回5.2 关键请求要求客户端POST必须带Accept: application/json, text/event-streamBody 是单个 JSON-RPC request/notification/response如果输入是 request服务端必须返回 JSON 或 SSE 之一。5.3 会话与版本头常见生产实现会用这两个头MCP-Session-Id初始化后由服务端分配会话级状态MCP-Protocol-Version后续请求携带协商版本如2025-11-25如果携带的 session 失效服务端可回404客户端应重新initialize。5.4 最小时序POST /mcp initialize POST /mcp notifications/initialized POST /mcp tools/list POST /mcp tools/call5.5 为什么它更适合新系统单端点模型路由与网关更清晰同时覆盖“简单 JSON 返回”与“流式 SSE 返回”更利于标准化认证、审计、会话管理6. 一个容易混淆的点SSE 有两种语境很多团队会把“支持 SSE”理解错。这里明确区分旧传输HTTPSSElegacy transport它本身是一套旧传输协议模型新传输里的 SSE 流streamable-http text/event-stream这是新传输中的“响应形态”之一不等于你在使用旧 transport7. 选型建议按场景7.1 本机工具链CLI / IDE / 自动化脚本优先stdio。原因低成本、快启动、好调试。7.2 团队共享服务 / 云端 Agent 平台优先streamable-http。原因多客户端、鉴权、网关、可观测性都更自然。7.3 老系统平滑迁移短期双栈legacy SSE streamable-http。做法先让服务端同时支持新旧客户端优先尝试新传输新传输失败再回退旧传输完成客户端升级后下线旧端点8. 迁移路线SSE - streamable-http8.1 服务端迁移新增/mcp单端点保留旧 SSEPOST 端点一段时间统一认证、日志与 trace id监控新旧流量比例8.2 客户端迁移对用户输入的 URL 先POST initialize按新传输若返回400/404/405再尝试旧 SSE 握手一旦新传输成功固定走新传输8.3 下线标准旧端点调用量低于阈值例如 1%一段观察期内无关键告警所有核心客户端版本均完成升级9. 调试与排障清单9.1 stdio 模式看 server 日志是否误写到stdout检查是否有非法前缀输出banner、彩色日志检查换行分隔是否正确9.2 streamable-http 模式URL 必须包含 MCP endpoint例如/mcpAccept头是否正确是否携带了正确的MCP-Session-Id返回404是否触发了重新初始化代理是否剥离了 SSE 相关 header9.3 WSL/本机网络如果在 Windows WSL 里出现localhost可用但127.0.0.1不可用或反过来优先使用实际可通地址并检查服务绑定地址127.0.0.1/0.0.0.0端口转发与防火墙策略Host 与 WSL 的回环映射行为10. 你可以直接复用的“团队规范”建议在团队内统一这 5 条新项目默认streamable-http本地开发可stdio所有新服务都必须支持initialize - initialized强制记录trace_id / request_id / server_name / method / latency高风险工具必须有鉴权和确认门禁旧HTTPSSE只作为迁移兼容不新增依赖11. 一页总结stdio本地最稳开发最快HTTPSSE旧历史兼容逐步下线streamable-http当前远程标准方案判断标准很务实单机调试优先stdio远程共享优先streamable-http能不用旧 SSE 就不要再新增旧 SSE12. 官方参考建议收藏最新传输规范2025-11-25https://modelcontextprotocol.io/specification/2025-11-25/basic/transports旧版传输规范2024-11-05https://modelcontextprotocol.io/specification/2024-11-05/basic/transports生命周期initialize / initializedhttps://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle13. 三种模式的最小上手示例13.1 stdio本地子进程Codex CLI 配置示例[mcp_servers.local_stdio] command python args [/abs/path/to/server.py]13.2 streamable-http新Codex CLI 配置示例[mcp_servers.remote_http] url http://localhost:8000/mcp最小连通性测试initializecurl-i-XPOST http://localhost:8000/mcp\-HContent-Type: application/json\-HAccept: application/json, text/event-stream\-d{jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2025-11-25,capabilities:{tools:{}},clientInfo:{name:manual,version:0.1}}}13.3 旧 HTTPSSElegacy建立 SSEcurl-Nhttp://localhost:8000/sse再按endpoint事件给出的 URL 发POSTJSON-RPC 请求。
MCP 的三种数据传输模式教程（stdio / SSE / Streamable HTTP）
MCP 的三种数据传输模式教程stdio / SSE / Streamable HTTP适用日期2026-03-25术语说明本文的“SSE 模式”指旧版 HTTPSSE 传输legacy不是 Streamable HTTP 中可选的 SSE 流式响应。1. 优先级如果你现在在做新项目优先级应该是本地单机场景stdio远程服务化场景streamable-httpHTTPSSE旧版仅用于兼容历史客户端/服务端原因很简单MCP 最新规范2025-11-25标准传输是stdio streamable-http旧HTTPSSE已被替代保留主要是向后兼容1.1 版本时间线2024-11-05规范里有stdio与旧HTTPSSE传输2025-03-26规范开始将远程 HTTP 方向切到streamable-http2025-11-25streamable-http成为当前主方案旧HTTPSSE进入兼容语义如果你在文档里看到 “SSE transport”先确认是哪个版本的规范不要混在一起解读。2. 三种模式总览对比维度stdioHTTPSSE旧streamable-http新连接形态客户端拉起子进程远程 HTTP 双端点远程 HTTP 单端点标准状态当前标准已废弃兼容当前标准通信方式stdin/stdout 行分隔 JSON-RPCSSE 收消息 POST 发消息POST 发消息响应可 JSON 或 SSE也可 GET 打开 SSE典型部署本机工具、IDE 插件历史系统云服务、网关、多客户端复杂度低中-高中关键风险stdout 混入日志端点管理复杂鉴权、会话、重连3. 模式一stdio3.1 适合什么场景MCP Server 与客户端部署在同一台机器你希望最小化网络、鉴权、反向代理复杂度开发调试阶段先跑通能力3.2 通信模型Client 启动 Server 子进程 Client - (stdin) - Server Server - (stdout) - Client stderr 仅用于日志规范关键点JSON-RPC 消息按“每行一条”分隔消息不能包含内嵌换行stdout只能输出合法 MCP 消息日志写stderr不要写stdout3.3 最小示例配置思路[mcp_servers.my_local_stdio] command python args [/path/to/server.py]3.4 优缺点优点简单、稳定、延迟低不涉及 HTTP 暴露面缺点不能天然做远程多客户端共享进程生命周期由客户端托管运维能力较弱3.5 常见坑Server 把日志打印到stdout导致 JSON-RPC 解析失败某些库输出 banner 到stdout子进程环境变量不完整导致认证失败4. 模式二HTTPSSE旧版legacy这是历史方案常见于老 MCP 客户端。新系统建议迁移到streamable-http。4.1 它是怎么工作的旧模式需要两个端点SSE 端点客户端建立事件流、接收服务端消息POST 端点客户端把 JSON-RPC 发给服务端建立连接后服务端先在 SSE 流发一个endpoint事件告诉客户端“后续 POST 发到哪个 URL”。4.2 典型时序GET /sse (打开 SSE) - event: endpoint data: {uri:/messages?...} POST /messages?... (发送 JSON-RPC) - event: message data: {...JSON-RPC...}4.3 为什么被替代模型简单但端点分裂集成成本高与现代 API 网关和统一路由模型不够一致新规范将远程通信统一到streamable-http4.4 什么时候还会用到你的客户端仍停留在老协议栈你在做历史系统迁移期双栈兼容5. 模式三streamable-http推荐5.1 核心特征使用一个 MCP endpoint如/mcp该端点必须支持POST可选支持GETPOST发送 JSON-RPC响应可为application/json单次返回text/event-streamSSE 流式返回5.2 关键请求要求客户端POST必须带Accept: application/json, text/event-streamBody 是单个 JSON-RPC request/notification/response如果输入是 request服务端必须返回 JSON 或 SSE 之一。5.3 会话与版本头常见生产实现会用这两个头MCP-Session-Id初始化后由服务端分配会话级状态MCP-Protocol-Version后续请求携带协商版本如2025-11-25如果携带的 session 失效服务端可回404客户端应重新initialize。5.4 最小时序POST /mcp initialize POST /mcp notifications/initialized POST /mcp tools/list POST /mcp tools/call5.5 为什么它更适合新系统单端点模型路由与网关更清晰同时覆盖“简单 JSON 返回”与“流式 SSE 返回”更利于标准化认证、审计、会话管理6. 一个容易混淆的点SSE 有两种语境很多团队会把“支持 SSE”理解错。这里明确区分旧传输HTTPSSElegacy transport它本身是一套旧传输协议模型新传输里的 SSE 流streamable-http text/event-stream这是新传输中的“响应形态”之一不等于你在使用旧 transport7. 选型建议按场景7.1 本机工具链CLI / IDE / 自动化脚本优先stdio。原因低成本、快启动、好调试。7.2 团队共享服务 / 云端 Agent 平台优先streamable-http。原因多客户端、鉴权、网关、可观测性都更自然。7.3 老系统平滑迁移短期双栈legacy SSE streamable-http。做法先让服务端同时支持新旧客户端优先尝试新传输新传输失败再回退旧传输完成客户端升级后下线旧端点8. 迁移路线SSE - streamable-http8.1 服务端迁移新增/mcp单端点保留旧 SSEPOST 端点一段时间统一认证、日志与 trace id监控新旧流量比例8.2 客户端迁移对用户输入的 URL 先POST initialize按新传输若返回400/404/405再尝试旧 SSE 握手一旦新传输成功固定走新传输8.3 下线标准旧端点调用量低于阈值例如 1%一段观察期内无关键告警所有核心客户端版本均完成升级9. 调试与排障清单9.1 stdio 模式看 server 日志是否误写到stdout检查是否有非法前缀输出banner、彩色日志检查换行分隔是否正确9.2 streamable-http 模式URL 必须包含 MCP endpoint例如/mcpAccept头是否正确是否携带了正确的MCP-Session-Id返回404是否触发了重新初始化代理是否剥离了 SSE 相关 header9.3 WSL/本机网络如果在 Windows WSL 里出现localhost可用但127.0.0.1不可用或反过来优先使用实际可通地址并检查服务绑定地址127.0.0.1/0.0.0.0端口转发与防火墙策略Host 与 WSL 的回环映射行为10. 你可以直接复用的“团队规范”建议在团队内统一这 5 条新项目默认streamable-http本地开发可stdio所有新服务都必须支持initialize - initialized强制记录trace_id / request_id / server_name / method / latency高风险工具必须有鉴权和确认门禁旧HTTPSSE只作为迁移兼容不新增依赖11. 一页总结stdio本地最稳开发最快HTTPSSE旧历史兼容逐步下线streamable-http当前远程标准方案判断标准很务实单机调试优先stdio远程共享优先streamable-http能不用旧 SSE 就不要再新增旧 SSE12. 官方参考建议收藏最新传输规范2025-11-25https://modelcontextprotocol.io/specification/2025-11-25/basic/transports旧版传输规范2024-11-05https://modelcontextprotocol.io/specification/2024-11-05/basic/transports生命周期initialize / initializedhttps://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle13. 三种模式的最小上手示例13.1 stdio本地子进程Codex CLI 配置示例[mcp_servers.local_stdio] command python args [/abs/path/to/server.py]13.2 streamable-http新Codex CLI 配置示例[mcp_servers.remote_http] url http://localhost:8000/mcp最小连通性测试initializecurl-i-XPOST http://localhost:8000/mcp\-HContent-Type: application/json\-HAccept: application/json, text/event-stream\-d{jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2025-11-25,capabilities:{tools:{}},clientInfo:{name:manual,version:0.1}}}13.3 旧 HTTPSSElegacy建立 SSEcurl-Nhttp://localhost:8000/sse再按endpoint事件给出的 URL 发POSTJSON-RPC 请求。
