Streamable HTTP

Streamable HTTP 在协议版本 2025-03-26 中引入，作为协议版本 2024-11-05 中 HTTP+SSE 传输的替代方案。

2026-07-28 的修订更改了 Streamable HTTP 的行为。客户端必须确保正确处理向后兼容性。变更包括：

移除了 GET 流端点。
移除了协议级会话。

在 Streamable HTTP 传输中，服务器作为一个独立进程运行，能够处理多个客户端连接。简而言之：

服务器暴露一个单一的 HTTP 端点（MCP endpoint），接受 POST。
客户端将每个 JSON-RPC 请求或通知作为各自独立的 HTTP POST 发送。
服务器对每个请求返回单个 JSON 对象，或者返回一个作用域限定到该请求的 Server-Sent Events（SSE）流，该流携带与请求相关的通知，随后是最终响应。
服务器到客户端的交互（sampling、elicitation、roots）作为输入请求嵌入到结果中，遵循 Multi Round-Trip Requests (MRTR)（SEP-2322）。
长生命周期的变更通知（例如列表变更和资源更新）通过 subscriptions/listen 请求的响应流传递。

有关这些交互的时序图，请参见消息流。服务器 MUST 提供一个支持 POST 的单一 HTTP 端点路径（以下称为 MCP endpoint）。例如，这可以是一个类似 https://example.com/mcp 的 URL。

安全性与端点

在实现 Streamable HTTP 传输时：

服务器 MUST 验证所有传入连接上的 Origin 标头，以防止 DNS rebinding 攻击。
- 如果存在 Origin 标头且无效，服务器 MUST 返回 HTTP 403 Forbidden。HTTP 响应体 MAY 包含一个没有 id 的 JSON-RPC 错误响应。
在本地运行时，服务器 SHOULD 只绑定到 localhost（127.0.0.1），而不是所有网络接口（0.0.0.0）。
服务器 SHOULD 对所有连接实施适当的身份验证。

如果没有这些保护，攻击者可能利用 DNS rebinding 从远程网站与本地 MCP 服务器交互。

发送消息

客户端发送的每条 JSON-RPC 消息 MUST 都是到 MCP endpoint 的一个新的 HTTP POST 请求。

客户端 MUST 使用 HTTP POST 发送 JSON-RPC 消息。
客户端 MUST 包含一个 Accept 标头，列出 application/json 和 text/event-stream 作为受支持的内容类型。
客户端 MUST 在每个 POST 请求中包含请求元数据标头。
HTTP POST 的主体 MUST 是单个 JSON-RPC request 或 notification。客户端 MUST NOT 发送 JSON-RPC responses。
如果主体是 JSON-RPC notification：
- 如果服务器接受它，服务器 MUST 返回 HTTP 状态码 202 Accepted，且没有响应体。
- 如果服务器无法接受它，它 MUST 返回一个 HTTP 错误状态码（例如 400 Bad Request）。HTTP 响应体 MAY 包含一个没有 id 的 JSON-RPC 错误响应。
如果主体是 JSON-RPC request，服务器 MUST 返回 Content-Type: application/json（单个 JSON 对象）或 Content-Type: text/event-stream（SSE 响应流）之一。客户端 MUST 同时支持两者。

本核心协议的此修订版未定义通过 Streamable HTTP 的客户端到服务器的 notifications。核心协议中唯一由客户端发送的通知 notifications/cancelled 仅用于 stdio 传输；在 Streamable HTTP 中，关闭 SSE 响应流本身就是取消信号，并且不期望出现 notifications/cancelled 消息（见取消）。上面的通知规则描述的是通知 POST 的传输机制；本修订版未定义通知 POST 的头要求。

接收消息

当服务器返回 SSE 响应流（Content-Type: text/event-stream）时：

服务器 MAY 发送 JSON-RPC notifications——例如 notifications/progress 或 notifications/message — 在最终响应之前发送。这些通知 MUST 与发起该通知的客户端请求相关联。
服务器 MUST NOT 在此流上发送独立的 JSON-RPC requests。服务器到客户端的交互（sampling、elicitation、list-roots）作为输入请求嵌入到 InputRequiredResult 中，遵循 MRTR（SEP-2322），而不是作为单独的请求在此流或任何其他流上发送。这是对协议版本 2025-03-26 至 2025-11-25 中 Streamable HTTP 的一项更改；在这些版本中，服务器可以在 SSE 流上发送此类请求。
最终的 JSON-RPC response SHOULD 终止该流。

长生命周期的通知流可通过发送 subscriptions/listen request。服务器的响应本身是一个保持打开的 SSE 流，并投递客户端选择订阅的变更通知（例如 notifications/tools/list_changed 或 notifications/resources/updated）。诸如 notifications/progress 和 notifications/message 之类按请求作用域的通知不会在 listen 流上投递——它们只会在其所关联请求的响应流中传输。在启动 SSE 流时，服务器 SHOULD 在 HTTP 响应中包含 X-Accel-Buffering: no 头。这会指示反向代理（例如 nginx）禁用响应缓冲，确保 SSE 事件能够立即传递给客户端，而不是被保留在缓冲区中。没有该头时，代理可能会在发送给客户端之前累积消息，从而引入不必要的延迟，并可能破坏 SSE 通信的实时特性。

对于长生命周期流——尤其是 subscriptions/listen 响应流——建议服务器定期发送一行 SSE 注释（以冒号开头的行，例如 :\r\n）作为保活。这样可以避免在空闲期没有通知流动时，连接被中间代理或客户端空闲超时关闭。根据 SSE 规范，任何以冒号开头的行都是不携带事件数据的注释；客户端必须忽略此类行，且不得将其视为格式错误的输入。

不支持通过 Last-Event-ID 恢复 SSE 流。

消息流

以下图示展示了单个 MCP endpoint 上的消息流。 请求与响应。 每个请求都是一个独立的 POST；服务器会针对每个请求自行决定返回单个 JSON 对象还是 SSE 流： 服务器到客户端交互（MRTR）。 当服务器需要来自客户端的输入——sampling、elicitation 或 roots——它不会发送自己的 JSON-RPC 请求。它会返回一个包含 inputRequests 的 InputRequiredResult，而客户端会携带匹配的 inputResponses 重试原始请求（参见 Multi Round-Trip Requests）： 变更通知。 希望接收服务器发起的变更通知的客户端会使用 subscriptions/listen 打开一个长生命周期流；响应流保持打开状态，并且只携带客户端选择接收的通知类型：

取消

关闭 SSE 响应流必须被服务器视为该请求的取消。由于每个请求都有自己的响应流，因此传输级断开是明确无歧义的。服务器应该尽快停止已取消请求的工作，并且不得为其发送任何后续消息。完整规则请参见取消。

请求元数据

Streamable HTTP 传输会将选定的 JSON-RPC 正文字段镜像到 HTTP 头中，以便中介层（负载均衡器、网关、可观测性工具）无需解析正文即可路由和检查请求。

协议版本头

发送到 MCP endpoint 的每个 POST 请求必须包含一个 MCP-Protocol-Version 头。例如：MCP-Protocol-Version: 2026-07-28 该头值必须与请求正文的 _meta 中携带的 io.modelcontextprotocol/protocolVersion 字段匹配。如果这些值不匹配，服务器必须拒绝该请求，返回 400 Bad Request 和一个 HeaderMismatch JSON-RPC 错误（见 Server Validation）。如果服务器未实现所请求的协议版本（无论该版本对服务器而言是未知版本，还是服务器已知但选择不支持的版本），它必须返回 400 Bad Request 和一个 UnsupportedProtocolVersionError，列出其支持的版本。请参见 Versioning: Protocol Version Negotiation 了解协商流程。如果服务器未实现所请求的 RPC 方法，它必须返回 404 Not Found 和一个错误码为 -32601 （Method not found）的 JSON-RPC 错误。该 JSON-RPC 错误体将此情形与由不托管现代 MCP endpoint 的旧版 HTTP+SSE 服务器返回的 404 区分开来（见 Backward Compatibility）。支持早于 2025-06-18 的协议版本客户端（该版本未定义 MCP-Protocol-Version 头）的服务器可以将缺少该头的请求视为协议版本 2025-03-26。不支持此类客户端的服务器必须按照 Server Validation 拒绝缺少该头的请求。

标准请求头

头名称	来源字段	适用范围
`Mcp-Method`	`method`	所有请求
`Mcp-Name`	`params.name` or `params.uri`	`tools/call`、`resources/read`、`prompts/get` 请求

这些头对于符合规范是 必需的。如果 Mcp-Name 的来源值无法安全地表示为普通 ASCII 头值，客户端必须按照值编码中描述的 Base64 哨兵格式对其进行编码。 tools/call 请求：

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: get_weather

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "Seattle, WA"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

resources/read 请求：

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: resources/read
Mcp-Name: file:///projects/myapp/config.json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "file:///projects/myapp/config.json",
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

来自工具参数的自定义头

MCP 服务器可以使用参数的 schema 中的 inputSchema 内的 x-mcp-header 扩展属性，将特定工具参数映射到 HTTP 头中。详见工具定义，了解如何为工具参数添加注解。虽然服务器使用 x-mcp-header 是可选的，但客户端必须支持此功能。当服务器的工具定义包含 x-mcp-header 注解时，符合规范的客户端必须将指定的参数值映射到 HTTP 头中。

Schema 扩展

x-mcp-header 属性指定用于构造头名称 Mcp-Param-{name} 的名称部分。 x-mcp-header 值的约束：

MUST NOT be empty
MUST match HTTP field-name token syntax (1*tchar, RFC 9110 Section 5.1)
MUST NOT contain control characters, including carriage return (CR, \r) or line feed (LF, \n)
MUST be case-insensitively unique among all x-mcp-header values in the inputSchema
MUST only be applied to parameters with primitive types (integer, string, boolean). Parameters with type number are not permitted. Integer values MUST be within the safe range for integers represented using IEEE754 double-precision floating point numbers (−2⁵³+1 to 2⁵³−1)
MUST only be applied to properties that are statically reachable from the schema root: reachable via a chain consisting solely of properties keys. The chain MUST NOT pass through items (or any other array keyword), composition keywords (oneOf, anyOf, allOf, not), conditional keywords (if/then/else), or $ref. Nested object properties are permitted as long as every step in the chain is a properties key. An x-mcp-header annotation anywhere else makes the annotation — and thus the tool definition — invalid.

头提取被定义为读取带注解属性的精确属性路径上的实例值（通往它的 properties 键链）。如果调用参数中该路径没有值，则省略该头。使用 Streamable HTTP 传输的客户端必须拒绝任何 x-mcp-header 值违反这些约束的工具定义。拒绝意味着客户端必须将该无效工具从 tools/list 的结果中排除。客户端应该在拒绝工具定义时记录警告，包括工具名称和被拒绝的原因。这样可以确保单个格式错误的工具定义不会阻止其他有效工具的使用。使用其他传输方式（例如 stdio）的客户端可以完全忽略 x-mcp-header 注解。 工具定义示例：

{
  "name": "execute_sql",
  "description": "在 Google Cloud Spanner 上执行 SQL",
  "inputSchema": {
    "type": "object",
    "properties": {
      "region": {
        "type": "string",
        "description": "执行查询的区域",
        "x-mcp-header": "Region"
      },
      "query": {
        "type": "string",
        "description": "要执行的 SQL 查询"
      }
    },
    "required": ["region", "query"]
  }
}

生成的 HTTP 请求：

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: execute_sql
Mcp-Param-Region: us-west1

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "name": "execute_sql",
    "arguments": {
      "region": "us-west1",
      "query": "SELECT * FROM users"
    }
  }
}

值编码

客户端必须在将参数值包含到 HTTP 头之前对其进行编码，以确保安全传输并防止注入攻击。 类型转换：将参数值转换为其字符串表示形式：

string: 原样使用该值
integer: 转换为十进制字符串表示形式（例如 42、-7）
boolean: 转换为小写 "true" 或 "false"

根据 RFC 9110， HTTP 头字段值必须由可见 ASCII 字符（0x21-0x7E）、空格（0x20）以及水平制表符（0x09）组成。当某个值无法安全地表示为普通 ASCII 头值时（例如，它包含非 ASCII 字符、控制字符，或具有前导/尾随空白），客户端必须使用其 UTF-8 表示的 Base64 编码，格式如下：

Mcp-Param-{Name}: =?base64?{Base64EncodedValue}?=

相同的编码规则适用于 Mcp-Name 头值。工具和提示名称仅应该受限于对头部安全的字符，因此超出安全集合的名称（或资源 URI）将按如下方式传递：

Mcp-Name: =?base64?{Base64EncodedValue}?=

前缀 =?base64? 和后缀 ?= 表示该值已使用 Base64 编码。这些标记区分大小写，并且必须以所示的精确形式出现（小写）。需要检查这些值的服务器和中介组件必须进行相应解码。特别是，服务器必须在将编码后的 Mcp-Name 或 Mcp-Param-{Name} 值与请求正文中的相应值进行比较之前先对其解码，参见服务器校验。为避免歧义，客户端必须还要对任何匹配哨兵模式的纯 ASCII 值进行 Base64 编码（即，以 =?base64? 开头并以 ?= 结尾）。 编码示例：

原始值	原因	编码后的头值
`"us-west1"`	纯 ASCII	`Mcp-Param-Region: us-west1`
`"Hello, 世界"`	包含非 ASCII	`Mcp-Param-Greeting: =?base64?SGVsbG8sIOS4lueVjA==?=`
`" padded "`	前导/尾随空格	`Mcp-Param-Text: =?base64?IHBhZGRlZCA=?=`
`"line1\nline2"`	包含换行符	`Mcp-Param-Text: =?base64?bGluZTEKbGluZTI=?=`
`"=?base64?literal?="`	匹配哨兵模式	`Mcp-Param-Val: =?base64?PT9iYXNlNjQ/bGl0ZXJhbD89?=`

客户端行为

当通过 HTTP 传输构造 tools/call 请求时，客户端必须：

从请求正文中提取任何标准头的值（例如， method、params.name、params.uri）。
将 Mcp-Method 头以及（如适用）Mcp-Name 头附加到请求中。
检查工具的 inputSchema 中标记了 x-mcp-header 的属性，并提取每个已注解属性精确属性路径上的值；如果没有值则省略该头（见 Schema Extension）。
按照值编码规则对这些值进行编码。
将 Mcp-Param-{Name}: {Value} 头附加到请求中。

如果服务器因为所需的 Mcp-Param-* 头缺失或与正文不匹配而返回 HeaderMismatch 错误，客户端应该调用 tools/list 以检查工具的 inputSchema 是否有变化，然后使用适当的头重试原始请求。

服务器对自定义头的行为

不识别 Mcp-Param-{Name} 头的中介服务器必须转发它，并在其他方面忽略它，正如 HTTP 语义 RFC 所要求的那样。服务器必须拒绝包含无效字符的、被识别的 Mcp-Param-{Name} 头（见值编码）。任何处理消息正文的服务器必须验证编码后的头值（如果是 Base64 编码，则在解码后）与正文中的相应值匹配。若任何验证失败，服务器必须返回 HTTP 状态 400 Bad Request，并使用 JSON-RPC 错误码 -32020（HeaderMismatch）拒绝该请求。

场景	客户端行为	服务器行为
提供了参数值	客户端必须包含该头	服务器必须验证头与正文匹配
参数值为 `null`	客户端必须省略该头	服务器不得期望该头
参数未出现在参数中	客户端必须省略该头	服务器不得期望该头
客户端省略头但正文中有值	不符合规范的客户端	服务器必须拒绝该请求

大小写敏感性

头名称（在 RFC 9110 中称为“字段名”）是不区分大小写的。客户端和服务器 MUST 对头名称使用不区分大小写的比较。头_值_（例如方法名）是区分大小写的。

服务器验证

处理请求正文的服务器 MUST 拒绝那些其头中指定的值与请求正文中的相应值不匹配的请求。这可防止在网络中不同组件依赖不同事实来源时出现潜在安全漏洞（例如，负载均衡器根据头值进行路由，而 MCP 服务器根据正文值执行）。

在验证整数参数值时，服务器 SHOULD 以数值方式而不是字符串方式比较头值和正文值（例如， 42.0 和 42 被视为相等）。

当由于头验证失败而拒绝请求时，服务器 MUST 返回 HTTP 状态 400 Bad Request，并且 MUST 使用以下错误码包含一个 JSON-RPC 错误响应：

Code	Name	Description
`-32020`	`HeaderMismatch`	HTTP 头与请求正文中的相应值不匹配，或者缺少/格式错误的必需头。

该错误码从 MCP 规范为协议定义错误保留的子范围中分配。请参见错误码。 错误响应示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32020,
    "message": "头不匹配：Mcp-Name 头值 'foo' 与正文值 'bar' 不匹配"
  }
}

验证失败的条件包括：

缺少必需的标准头（MCP-Protocol-Version、Mcp-Method、 Mcp-Name）。
头值与对应的请求正文值不匹配。对于允许使用 Base64 哨兵编码的头（Mcp-Name 和 Mcp-Param-{Name}），服务器 MUST 在将编码值与正文值比较前先将其解码（见值编码）。
头值包含无效字符。

中介层 MUST 在验证失败时返回适当的 HTTP 错误状态（例如， 400 Bad Request），但不要求返回 JSON-RPC 错误响应。

实施基于镜像头的策略的中介层（例如按租户路由或限流）SHOULD 验证 MCP-Protocol-Version 头所指示的版本是否需要进行头-正文验证。如果该版本较旧或缺少该头，中介层 SHOULD 拒绝该请求，而不是信任未经验证的头值。

向后兼容性

客户端可以通过首先尝试现代请求来检测对现代 MCP 版本（如请求元数据所示）以及需要 initialize 握手的旧版本，以判断服务器实现的是哪个时代。若收到 400 Bad Request，客户端应当在回退之前检查响应体：现代服务器也会对 UnsupportedProtocolVersionError、MissingRequiredClientCapabilityError 和请求头验证失败使用 400。

如果响应体包含可识别的现代 JSON-RPC 错误，则说明服务器支持现代 MCP 版本——应根据公布的 supported 版本重试，或修正请求，而不是回退。
如果响应体为空，或不包含可识别的现代 JSON-RPC 错误，则回退到 initialize，并在后续请求中继续使用旧版本。

关于时代模型和面向实现的兼容性矩阵，请参见版本管理：向后兼容性。

更早的 Streamable HTTP 修订版

协议版本 2025-03-26 到 2025-11-25 也使用了 Streamable HTTP 传输，但形式不同：服务器可以通过 Mcp-Session-Id 头分配会话（通过 HTTP DELETE 终止），客户端可以通过 HTTP GET 打开单独的 SSE 流以接收服务器发起的消息，服务器可以在 SSE 流上发送 JSON-RPC requests，并且流可以通过 Last-Event-ID 恢复。这些机制都不属于本修订版。只支持此修订版并接收到来自旧客户端的此类流量的服务器应当如下响应：

对 MCP 端点的 HTTP GET 或 DELETE：返回 405 Method Not Allowed。
请求中的 Mcp-Session-Id 头：忽略它；不要生成或回显会话 ID。
Last-Event-ID 头：忽略它；该流不可恢复。

需要与使用这些协议版本的对端互操作的服务器和客户端，除了实现上文所述的版本协商回退外，还应实现相应修订版中描述的行为（例如，2025-11-25: Streamable HTTP）。

HTTP+SSE 传输（2024-11-05）

已弃用：协议版本 2024-11-05 中的 HTTP+SSE 传输自协议版本 2025-03-26 起已被弃用，并且根据功能生命周期策略（SEP-2596）被归类为已弃用。新实现不应采用它；现有实现应当迁移到 Streamable HTTP。预计它将在未来的修订版中被移除；请参见已弃用功能登记表。

客户端和服务器可以通过以下方式保持与已弃用的 HTTP+SSE 传输（来自协议版本 2024-11-05）的向后兼容性： 希望支持旧客户端的服务器应当：

继续同时提供旧传输的 SSE 和 POST 端点，以及为 Streamable HTTP 传输定义的新 “MCP 端点”。
- 也可以将旧的 POST 端点与新的 MCP 端点合并，但这可能会引入不必要的复杂性。

希望支持旧服务器的客户端应当：

从用户处接受一个 MCP 服务器 URL，该 URL 可能指向使用旧传输或新传输的服务器。
对该服务器 URL 发起 POST 请求，并使用上文定义的 Accept 头：
- 如果成功，客户端可以假定这是支持新的 Streamable HTTP 传输的服务器。
- 如果失败并返回 HTTP 状态码 400 Bad Request、404 Not Found 或 405 Method Not Allowed，且响应体不是一个可识别的现代 JSON-RPC 错误（现代服务器会针对不支持的版本、未知方法或头验证失败返回此类错误）：
  - 向服务器 URL 发起 GET 请求，期望这会打开一个 SSE 流，并将 endpoint 事件作为第一个事件返回。
  - 收到 endpoint 事件后，客户端可以假定这是运行旧 HTTP+SSE 传输的服务器，并应在后续所有通信中使用该传输。

基础协议

客户端功能

服务器功能

安全性与端点

发送消息

接收消息

消息流

取消

请求元数据

协议版本头

标准请求头

来自工具参数的自定义头

Schema 扩展

值编码

客户端行为

服务器对自定义头的行为

大小写敏感性

服务器验证

向后兼容性

更早的 Streamable HTTP 修订版

HTTP+SSE 传输（2024-11-05）

​安全性与端点

​发送消息

​接收消息

​消息流

​取消

​请求元数据

​协议版本头

​标准请求头

​来自工具参数的自定义头

​Schema 扩展

​值编码

​客户端行为

​服务器对自定义头的行为

​大小写敏感性

​服务器验证

​向后兼容性

​更早的 Streamable HTTP 修订版

​HTTP+SSE 传输（2024-11-05）

安全性与端点

发送消息

接收消息

消息流

取消

请求元数据

协议版本头

标准请求头

来自工具参数的自定义头

Schema 扩展

值编码

客户端行为

服务器对自定义头的行为

大小写敏感性

服务器验证

向后兼容性

更早的 Streamable HTTP 修订版

HTTP+SSE 传输（2024-11-05）