modelcontextprotocol.io
MCP 2025-03-26 Transports Specification
Streamable HTTP 传输规范：单端点、有状态会话、可恢复连接的完整协议定义。
OpenAI Agents SDK #31：MCPServerStreamableHttp——MCP 三传输方式的最后一块拼图，2025-03-26 新规范完全拆解
MCPServerStreamableHttp 是 OpenAI Agents SDK 对 MCP 2025-03-26 新传输规范的正式实现。本期完整拆解 MCPServerStreamableHttpParams 的 8 个字段，重点解析 terminate_on_close 会话生命周期控制、session_id 跨进程会话复用、ignore_initialized_notification_failure 兼容性开关，以及内置的共享会话→隔离会话自动降级重试机制。附三种 MCP 传输方式七维横向对比矩阵与三条生产建议。
리서치 브리프
MCP 生态正在经历一次悄无声息的标准迁移。
2025 年 3 月 26 日，Model Context Protocol 规范发布重大更新：正式引入 Streamable HTTP 传输方式，同时将旧有的 HTTP+SSE 传输标记为「已弃用」。1
OpenAI Agents SDK 已跟进支持，新增
MCPServerStreamableHttp 类。至此，SDK 支持三种 MCP 传输方式，形成完整的三角：MCPServerStdio：本地子进程（#29 已覆盖）MCPServerSse：旧 HTTP+SSE 远程（#29 已覆盖）MCPServerStreamableHttp：新 Streamable HTTP 远程（本期主题）
中文社区目前没有任何关于
MCPServerStreamableHttp 的深度解读。本文从协议设计、SDK 参数、生产级实践三个维度系统拆解。링크 미리보기를 불러오는 중…
为什么要废弃 HTTP+SSE？
旧版 HTTP+SSE 传输设计上存在一个根本性的架构缺陷：需要两个分离的端点。
一个端点专门建立 SSE 长连接（服务端推送），另一个端点接收客户端 POST 消息。两条通道，两次握手，任何一端断开都需要重建整个连接。这在无状态部署（Serverless、容器化）环境下尤为棘手——连接不可恢复，断线即丢失上下文。2
Streamable HTTP 的核心答案是：一个端点，统一处理 POST 和 GET。
POST /mcp：客户端发 JSON-RPC 消息，服务端可以返回application/json（直接响应）或text/event-stream（升级为 SSE 流式响应）GET /mcp：客户端主动建立监听流，服务端向客户端主动推送消息
这不是「把两个端点合并」，而是彻底重新设计了通信模型：HTTP 连接本身成了可升级的双向通道。
SDK 中的 MCPServerStreamableHttp
参数结构
MCPServerStreamableHttp 继承自 _MCPServerWithClientSession，与 MCPServerSse 同属 HTTP 系列，但在参数结构上有几处关键差异。MCPServerStreamableHttpParams 是专属配置对象，8 个字段：| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | str | 必填 | Streamable HTTP 服务器地址 |
headers | dict[str, str] | — | 请求头，也用于传入 Mcp-Session-Id 恢复会话 |
timeout | timedelta | float | 5秒 | HTTP 请求超时 |
sse_read_timeout | timedelta | float | 300秒 | SSE 连接超时（5 分钟） |
terminate_on_close | bool | True | 关闭连接时是否终止服务端会话 |
httpx_client_factory | 工厂函数 | — | 自定义 httpx.AsyncClient，用于注入代理、证书等 |
auth | httpx.Auth | None | — | httpx 认证处理器，支持 OAuth 刷新等场景 |
ignore_initialized_notification_failure | bool | False | 是否忽略初始化通知发送失败 |
外层初始化参数与
MCPServerStdio/MCPServerSse 一致，主要是 cache_tools_list、name、tool_filter、max_retry_attempts、retry_backoff_seconds_base 等继承自父类的通用参数。3两个独有参数的深层含义
terminate_on_close（默认 True）Streamable HTTP 是有状态会话协议——服务端会为每个连接颁发
Mcp-Session-Id，维护会话上下文。terminate_on_close=True 意味着：当 async with MCPServerStreamableHttp(...) as server: 块退出时，SDK 会向服务端发送 HTTP DELETE 请求，显式终止服务端会话，释放资源。如果你想复用会话（下文会讲），需要设置
terminate_on_close=False，并在下次连接时通过 headers 传入同一个 Mcp-Session-Id。ignore_initialized_notification_failure（默认 False）MCP 握手阶段，客户端需要发送一个
notifications/initialized 通知到服务端。部分服务端实现不完整，这条通知发送失败会导致整个连接中断。设置为 True 后，失败只记录日志，后续请求正常继续。这是一个兼容性开关，适用于对接第三方 MCP 服务端时碰到奇怪的握手失败问题。
session_id：跨进程会话复用
MCPServerStreamableHttp 新增了一个 MCPServerSse 没有的属性：session_id。async with MCPServerStreamableHttp(params={"url": url}) as server:
tools = await server.list_tools()
sid = server.session_id # 服务端颁发的会话 ID，连接期间稳定
print(f"Session: {sid}")
# 可持久化到数据库或传给下一个工作进程拿到
session_id 后，可以在新的进程或无状态 Worker 里恢复同一个服务端会话：async with MCPServerStreamableHttp(
params={
"url": url,
"headers": {"Mcp-Session-Id": sid},
"terminate_on_close": False, # 不终止，继续复用
}
) as server:
# 恢复原有会话上下文
result = await server.call_tool("continue_task", {...})这对需要会话状态的 MCP 服务器（比如维护文件系统操作历史、代码执行上下文的服务端）来说是关键能力。
링크 미리보기를 불러오는 중…
内置隔离重试机制
MCPServerStreamableHttp 的 call_tool 有一套比其他两种传输更精密的错误恢复逻辑：共享会话失败自动降级为隔离会话重试。正常情况下，工具调用通过共享的长连接会话执行。当共享连接因网络闪断、服务端重启、超时等原因失败时，SDK 判断是否符合可重试条件：
asyncio.CancelledError、连接重置（ClosedResourceError）httpx.ConnectError、httpx.TimeoutException- HTTP 5xx 错误（服务端错误）
- MCP
REQUEST_TIMEOUT错误
符合条件时，SDK 自动建立一个独立的隔离连接，用新连接重新执行工具调用，不影响其他并发请求。整个过程对上层代码透明。
这比手动设置
max_retry_attempts 更高效——max_retry_attempts 是全量重试，隔离重试只针对当次调用，且不需要等指数退避时间。基础用法
from agents.mcp import MCPServerStreamableHttp
async with MCPServerStreamableHttp(
params={
"url": "https://your-mcp-server.example.com/mcp",
"headers": {"Authorization": "Bearer your-token"},
"timeout": 10.0,
"sse_read_timeout": 600.0, # 长任务场景加大读取超时
},
name="my-remote-mcp",
cache_tools_list=True, # 工具列表不变时务必开启
max_retry_attempts=2,
retry_backoff_seconds_base=1.0,
) as server:
agent = Agent(
name="Assistant",
instructions="Use tools to complete tasks.",
mcp_servers=[server],
)
result = await Runner.run(agent, "执行任务...")与另外两种传输方式的对比
| 维度 | MCPServerStdio | MCPServerSse（弃用） | MCPServerStreamableHttp |
|---|---|---|---|
| 运行位置 | 本地子进程 | 远程 HTTP | 远程 HTTP |
| 端点数量 | N/A | 2 个（SSE 端点 + POST 端点） | 1 个（统一端点） |
| 会话管理 | 无 | 无 | 有（Mcp-Session-Id） |
| 断线恢复 | 重启进程 | 不可恢复 | 支持（Last-Event-Id） |
| 状态保持 | 进程内 | 无状态 | 跨连接可恢复 |
| 适合场景 | 本地工具、快速原型 | 旧服务端兼容 | 生产级远程 MCP 服务 |
| 规范状态 | 现行 | 已弃用 | 2025 新标准 |
三条生产建议
1. 新项目直接用 Streamable HTTP，别再新建 SSE 服务端
MCPServerSse 对应的 HTTP+SSE 传输在 MCP 2025-03-26 规范中正式标记为 deprecated。Cloudflare、AWS 等主流云服务商的 MCP 文档已将 Streamable HTTP 定为推荐标准。如果你在搭新的 MCP 服务端，直接对接 Streamable HTTP，省去后期迁移成本。2. 会话恢复与
terminate_on_close 组合使用无状态部署场景（Lambda、Cloud Run 等容器化函数）中，每次调用都新建连接会带来额外握手开销。通过 Redis 或外部存储持久化
session_id，搭配 terminate_on_close=False，可以在工作进程之间透明复用服务端会话状态。3.
cache_tools_list=True + 按需 invalidate_tools_cache()Streamable HTTP 的
list_tools() 延迟陷阱与 MCPServerSse 相同——每次 Agent run 都会触发一次 list 请求。工具列表固定时务必开缓存；服务端热更新工具后调用 server.invalidate_tools_cache() 手动刷新。MCP 生态的传输层正在完成标准化收敛：一个端点、有状态会话、可恢复连接。
MCPServerStreamableHttp 是 OpenAI Agents SDK 接入这个新标准的正式入口。OpenAI Agents SDK 三套 MCP 传输方式至此全部覆盖完毕。下期继续深挖 SDK 其他技术点。
링크 미리보기를 불러오는 중…
이 콘텐츠를 둘러싼 관점이나 맥락을 계속 보강해 보세요.