Streamable HTTP

• 服务器暴露一个接受 POST 的单一 HTTP 端点（MCP 端点）。
• 客户端将每个 JSON-RPC 请求或通知作为它自己的 HTTP POST 发送。
• 服务器以一个单一的 JSON 对象或一个限定于该请求的 Server-Sent Events（SSE）流回答每个请求，携带请求相关的通知，随后是最终响应。
• 服务器到客户端的交互（采样、征询、roots）根据多轮往返请求（MRTR）（SEP-2322）作为输入请求嵌入在结果中。
• 长期存在的变更通知（例如列表变更和资源更新）在一个 subscriptions/listen 请求的响应流上投递。

​

安全与端点

1. 服务器**必须（MUST）**校验所有传入连接上的 Origin header 以防止 DNS 重绑定攻击。
   • 如果 Origin header 存在且无效，服务器**必须（MUST）以 HTTP 403 Forbidden 响应。HTTP 响应体可以（MAY）**由一个没有 id 的 JSON-RPC _错误响应_构成。
2. 在本地运行时，服务器**应当（SHOULD）**只绑定到 localhost（127.0.0.1），而不是所有网络接口（0.0.0.0）。
3. 服务器**应当（SHOULD）**为所有连接实现适当的认证。

​

发送消息

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

​

接收消息

• 服务器**可以（MAY）在最终响应之前发送 JSON-RPC 通知——例如 notifications/progress 或 notifications/message。这些通知必须（MUST）**与发起的客户端请求相关。
• 服务器**不得（MUST NOT）**在此流上发送独立的 JSON-RPC 请求。服务器到客户端的交互（采样、征询、list-roots）根据 MRTR（SEP-2322）作为输入请求嵌入在一个 InputRequiredResult 内，而不是作为单独的请求在此流或任何其他流上投递。这是相对于协议版本 2025-03-26 到 2025-11-25 中的 Streamable HTTP 的一个变更，在那些版本中服务器可以在 SSE 流上发送此类请求。
• 最终的 JSON-RPC 响应**应当（SHOULD）**终止该流。

​

消息流

​

取消

​

请求元数据

​

协议版本 header

​

标准请求 header

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

​

来自工具参数的自定义 header

​

Schema 扩展

• **不得（MUST NOT）**为空
• **必须（MUST）**匹配 HTTP 字段名 token 语法（1*tchar，RFC 9110 第 5.1 节）
• **不得（MUST NOT）**包含控制字符，包括回车（CR，\r）或换行（LF，\n）
• 在 inputSchema 中的所有 x-mcp-header 值之间**必须（MUST）**大小写不敏感地唯一
• **必须（MUST）只应用于具有原始类型（integer、string、boolean）的参数。不允许类型为 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": "Execute SQL on Google Cloud Spanner",
  "inputSchema": {
    "type": "object",
    "properties": {
      "region": {
        "type": "string",
        "description": "The region to execute the query in",
        "x-mcp-header": "Region"
      },
      "query": {
        "type": "string",
        "description": "The SQL query to execute"
      }
    },
    "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. 从请求体中提取任何标准 header 的值（例如 method、params.name、params.uri）。
2. 将 Mcp-Method header 以及（如果适用）Mcp-Name header 附加到请求。
3. 检查工具的 inputSchema 中标记有 x-mcp-header 的属性，并提取每个被注解属性的确切属性路径处的值，当不存在值时省略该 header（参见 Schema 扩展）。
4. 根据值编码规则对这些值进行编码。
5. 将一个 Mcp-Param-{Name}: {Value} header 附加到请求。

​

自定义 header 的服务器行为

​

大小写敏感性

​

服务器校验

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

• 缺少一个必需的标准 header（MCP-Protocol-Version、Mcp-Method、Mcp-Name）。
• 一个 header 值与对应的请求体值不匹配。对于允许 Base64 哨兵编码的 header（Mcp-Name 和 Mcp-Param-{Name}），服务器在将它们与消息体值比较之前**必须（MUST）**解码编码后的值（参见值编码）。
• 一个 header 值包含无效字符。

​

向后兼容

• 如果消息体包含一个已识别的现代 JSON-RPC 错误，服务器讲的是一个现代版本的 MCP——使用公布的 supported 版本重试或纠正请求，而不是回退。
• 如果消息体为空或不是一个已识别的现代 JSON-RPC 错误，回退到 initialize 并在后续请求中继续使用旧式版本。

​

早期的 Streamable HTTP 修订版

• 对 MCP 端点的 HTTP GET 或 DELETE：以 405 Method Not Allowed 响应。
• 请求上的 Mcp-Session-Id header：忽略它，且不铸造或回传会话 ID。
• Last-Event-ID header：忽略它；流不可恢复。

​

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

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

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