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 请求的响应流传递。

​

安全性与端点

1. 服务器 MUST 验证所有传入连接上的 Origin 标头，以防止 DNS rebinding 攻击。
   • 如果存在 Origin 标头且无效，服务器 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 标头，列出 application/json 和 text/event-stream 作为受支持的内容类型。
3. 客户端 MUST 在每个 POST 请求中包含 请求元数据标头。
4. HTTP POST 的主体 MUST 是单个 JSON-RPC request 或 notification。客户端 MUST NOT 发送 JSON-RPC responses。
5. 如果主体是 JSON-RPC notification：
   • 如果服务器接受它，服务器 MUST 返回 HTTP 状态码 202 Accepted，且没有响应体。
   • 如果服务器无法接受它，它 MUST 返回一个 HTTP 错误状态码（例如 400 Bad Request）。HTTP 响应体 MAY 包含一个没有 id 的 JSON-RPC 错误响应。
6. 如果主体是 JSON-RPC request，服务器 MUST 返回 Content-Type: application/json（单个 JSON 对象）或 Content-Type: text/event-stream（SSE 响应流）之一。客户端 MUST 同时支持两者。

​

接收消息

• 服务器 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 扩展

• 不得 为空
• 必须 符合 HTTP field-name token 语法（1*tchar，RFC 9110 第 5.1 节）
• 不得 包含控制字符，包括回车符（CR，\r） 或换行符（LF，\n）
• 必须 在 inputSchema 中所有 x-mcp-header 值之间大小写不敏感地唯一
• 必须 仅应用于原始类型（integer、string、boolean）的参数。不允许类型为 number 的参数。 整数值 必须 位于 JavaScript 的安全范围内 （−2⁵³+1 到 2⁵³−1）
• 必须 仅应用于从 schema 根 静态可达 的属性：即仅通过由 properties 键组成的链可达。该链 不得 穿过 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 Extension）。
4. 按照 值编码 规则对这些值进行编码。
5. 将 Mcp-Param-{Name}: {Value} 头附加到请求中。

​

服务器对自定义头的行为

​

大小写敏感性

​

服务器验证

{
  "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 在将编码值与正文值比较前先将其解码（见 值编码）。
• 头值包含无效字符。

​

向后兼容性

• 如果响应体包含可识别的现代 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 传输的服务器，并应在后续所有通信中使用该 传输。