StreamableHTTP in depth

学习笔记：流式 HTTP 传输机制 (Streamable HTTP Transport)

一、核心问题与解决方案

• 挑战 (Challenge): MCP (Model/Client/Provider) 的某些功能（如采样、通知、日志）需要服务器向客户端发起请求，但标准 HTTP 协议难以实现服务器主动向客户端发起请求。
• 解决方案 (Solution): 采用“流式 HTTP 传输”作为一种变通方法 (Workaround)。

二、初始化流程 (Initialization Flow)

• 步骤 1：初始化请求 (Initialized Request): 客户端 → 服务器发送初始化请求 → 服务器返回结果。
• 步骤 2：初始化通知 (Initialized Notification): 客户端 → 服务器发送后续请求。
• 连接建立： 完成上述步骤后，服务器认为客户端已连接并准备就绪。
• 会话 ID (Session ID)： 服务器在响应中分配一个随机字符串作为 MCP 会话 ID，用于唯一标识客户端与服务器的连接。
• 后续请求要求： 客户端必须在所有后续请求中包含此会话 ID。

三、服务器向客户端发送消息的机制 (Server → Client)

• 关键步骤： 客户端在初始化完成后，可向 MCP 服务器发起一个 GET 请求，并包含会话 ID。
• 核心响应： 服务器返回一个 SSE (Server-Sent Events) 响应。
• 工作原理： SSE 是一种可以保持开放任意长时间的响应，允许服务器持续向客户端流式传输信息（如采样、日志、进度通知）。
• 目的： 利用这个长连接，服务器可以随时向客户端发送消息。

四、客户端向服务器调用工具的流程 (Client → Server)

• 步骤 1：工具调用请求 (Tool Call Request): 客户端向服务器发送工具调用请求（包含会话 ID）。
• 步骤 2：创建第二个 SSE 连接： 服务器会为本次工具调用打开一个新的 SSE 响应。
• 步骤 3：连接关闭： 一旦工具调用结果 (Tool Call Result) 被发送，这个用于工具调用的第二个 SSE 响应会自动关闭。
• 消息分流 (Message Routing)：
• 进度通知 (Progress Notification)： 通常发送到第一个（长连接）SSE 响应中。
• 日志/最终结果 (Logging/Result)： 发送到第二个（工具调用专用）SSE 响应中。

五、重要注意事项

• 会话 ID 的作用： 仅在流式 HTTP 传输中使用，标准 IO 传输不使用。
• 限制： 在某些场景下，如果设置特定的标志为 true，将破坏上述流式传输的变通机制。

Takeaways

• 流式 HTTP 传输通过采用 SSE (Server-Sent Events) 机制，解决了标准 HTTP 协议无法实现服务器主动向客户端推送消息（如日志、采样）的挑战。
• 客户端必须在所有后续请求中携带服务器分配的会话 ID (Session ID)，以确保连接的唯一性和可追溯性。
• 工具调用流程涉及两个 SSE 连接：第一个长连接用于接收进度通知，而第二个专用连接用于接收工具调用的日志和最终结果。