Streamable HTTP

• 服务器暴露单个 HTTP 端点（MCP 端点），并接受 POST。
• 客户端将每个 JSON-RPC 请求或通知作为各自独立的 HTTP POST 发送。
• 服务器对每个请求的响应要么是单个 JSON 对象，要么是一个仅针对该请求范围的 Server-Sent Events（SSE）流，其中包含与请求相关的通知，随后是最终响应。
• 服务器到客户端的交互（采样、询问、roots）会作为输入请求嵌入结果中，遵循 多轮往返请求（MRTR）（SEP-2322）。
• 长生命周期的变更通知（例如列表变更和资源更新）会通过 subscriptions/listen 请求的响应流传递。

​

安全与端点

1. 服务器 必须 在所有传入连接上验证 Origin 标头 以防止 DNS 重绑定攻击。
   • 如果 Origin 标头存在且无效，服务器 必须 响应 HTTP 403 Forbidden。HTTP 响应正文 可以 包含一个 不含 id 的 JSON-RPC 错误响应。
2. 在本地运行时，服务器 应当 仅绑定到 localhost （127.0.0.1），而不是所有网络接口（0.0.0.0）。
3. 服务器 应当 为所有连接实现适当的身份验证。

​

发送消息

1. 客户端必须使用 HTTP POST 发送 JSON-RPC 消息。
2. 客户端必须包含一个 Accept 请求头，其中同时列出 application/json 和 text/event-stream 作为受支持的内容类型。
3. 客户端必须在每个 POST 请求中包含请求元数据头 。
4. HTTP POST 的请求体必须是单个 JSON-RPC 请求 或 通知。客户端不得发送 JSON-RPC 响应。
5. 如果请求体是 JSON-RPC 通知：
   • 如果服务器接受它，服务器必须返回 HTTP 状态码 202 Accepted，且没有响应体。
   • 如果服务器无法接受它，必须返回一个 HTTP 错误状态码 （例如，400 Bad Request）。HTTP 响应体可以包含一个没有 id 的 JSON-RPC 错误响应。
6. 如果请求体是 JSON-RPC 请求，服务器必须返回以下任一内容： Content-Type: application/json（单个 JSON 对象）或 Content-Type: text/event-stream（SSE 响应流）。客户端 必须同时支持这两种形式。

​

接收消息

• 服务器 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 终止该流。

​

消息流

​

取消

​

请求元数据

​

协议版本头

​

标准请求头

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": {}
    }
  }
}

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": {}
    }
  }
}

​

来自工具参数的自定义头

​

Schema 扩展

• MUST NOT 为空
• MUST 匹配 HTTP field-name token 语法（1*tchar，RFC 9110 第 5.1 节）
• MUST NOT 包含控制字符，包括回车符（CR，\r） 或换行符（LF，\n）
• 在 inputSchema 中所有 x-mcp-header 值之间，MUST 以不区分大小写的方式保持唯一
• MUST 仅应用于原始类型（integer、string、boolean）的参数。不允许 type 为 number。整数值 MUST 位于 JavaScript 的安全范围内 （−2⁵³+1 到 2⁵³−1）
• MUST 仅应用于从 schema 根节点 静态可达 的属性：只能通过仅由 properties 键组成的链路到达。该链路 MUST NOT 穿过 items（或任何 其他数组关键字）、组合关键字（oneOf、anyOf、allOf、not）、条件关键字（if/then/else）或 $ref。只要链路中的每一步都是 properties 键，就允许嵌套对象属性。任何其他位置出现的 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"]
  }
}

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"
    }
  }
}

​

值编码

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

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

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

​

客户端行为

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

​

自定义头的服务器行为

​

大小写敏感性

​

服务器验证

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32020,
    "message": "Header mismatch: Mcp-Name header value 'foo' does not match body value 'bar'"
  }
}

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

​

向后兼容性

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

​

更早的 Streamable HTTP 修订版

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

​

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

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

1. 接受用户提供的 MCP 服务器 URL，该 URL 可能指向使用旧传输或新传输的服务器。
2. 尝试向服务器 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 传输的服务器，并应在后续所有通信中使用该传输。