传输

协议版本:2025-11-25

MCP 使用 JSON-RPC 来编码消息。JSON-RPC 消息必须使用 UTF-8 编码。

协议目前定义了两种用于客户端-服务器通信的标准传输机制:

  1. stdio,通过标准输入和标准输出进行通信
  2. 可流式 HTTP

客户端应该尽可能支持 stdio。

客户端和服务器也可以以可插拔方式实现自定义传输。

stdio

在 stdio 传输中:

  • 客户端将 MCP 服务器启动为子进程。
  • 服务器从其标准输入 (stdin) 读取 JSON-RPC 消息,并将消息发送到其标准输出 (stdout)。
  • 消息是单独的 JSON-RPC 请求、通知或响应。
  • 消息由换行符分隔,绝不能包含嵌入的换行符。
  • 服务器可以将 UTF-8 字符串写入其标准错误 (stderr),用于任何日志记录目的,包括信息性、调试和错误消息。
  • 客户端可以捕获、转发或忽略服务器的 stderr 输出,并不应该假设 stderr 输出表示错误条件。
  • 服务器绝不能向其 stdout 写入任何不是有效 MCP 消息的内容。
  • 客户端绝不能向服务器的 stdin 写入任何不是有效 MCP 消息的内容。
  sequenceDiagram
    participant Client
    participant Server Process

    Client->>+Server Process: 启动子进程
    loop 消息交换
        Client->>Server Process: 写入 stdin
        Server Process->>Client: 写入 stdout
        Server Process--)Client: 可选的 stderr 日志
    end
    Client->>Server Process: 关闭 stdin,终止子进程
    deactivate Server Process

可流式 HTTP

这取代了协议版本 2024-11-05 中的 HTTP+SSE 传输。请参阅下面的向后兼容性 指南。

在可流式 HTTP传输中,服务器作为可以处理多个客户端连接的独立进程运行。此传输使用 HTTP POST 和 GET 请求。 服务器可以选择性地使用服务器发送事件 (SSE) 来流式传输 多个服务器消息。这允许基本的 MCP 服务器,以及支持流式传输和服务器到客户端通知和请求的功能更丰富的服务器。

服务器必须提供单个 HTTP 端点路径(此后称为MCP 端点),该端点同时支持 POST 和 GET 方法。例如,这可以是一个类似 https://example.com/mcp 的 URL。

安全警告

实现可流式 HTTP 传输时:

  1. 服务器必须在所有传入连接上验证 Origin 头以防止 DNS 重新绑定攻击
    • 如果存在 Origin 头且无效,服务器必须响应 HTTP 403 Forbidden。HTTP 响应主体可以构成没有 id 的 JSON-RPC 错误响应
  2. 在本地运行时,服务器应该仅绑定到 localhost (127.0.0.1) 而不是所有网络接口 (0.0.0.0)
  3. 服务器应该为所有连接实现适当的身份验证

如果没有这些保护,攻击者可以使用 DNS 重新绑定从远程网站与本地 MCP 服务器交互。

向服务器发送消息

从客户端发送的每个 JSON-RPC 消息必须是对 MCP 端点的新的 HTTP POST 请求。

  1. 客户端必须使用 HTTP POST 向 MCP 端点发送 JSON-RPC 消息。
  2. 客户端必须包含 Accept 头,将 application/json 和 text/event-stream 列为支持的内容类型。
  3. POST 请求的主体必须是单个 JSON-RPC 请求、通知_或_响应。
  4. 如果输入是 JSON-RPC 响应_或_通知:
    • 如果服务器接受输入,服务器必须返回 HTTP 状态代码 202 Accepted 且没有主体。
    • 如果服务器无法接受输入,它必须返回 HTTP 错误状态代码(例如 400 Bad Request)。HTTP 响应主体可以构成没有 id 的 JSON-RPC 错误响应。
  5. 如果输入是 JSON-RPC 请求,服务器必须要么返回 Content-Type: text/event-stream 以启动 SSE 流,要么返回 Content-Type: application/json 以返回一个 JSON 对象。客户端必须支持这两种情况。
  6. 如果服务器启动 SSE 流:
    • 服务器应该立即发送一个由事件 ID 和空 data 字段组成的 SSE 事件,以使客户端准备好重新连接(使用该事件 ID 作为 Last-Event-ID)。
    • 在服务器向客户端发送带有事件 ID 的 SSE 事件后,服务器可以随时关闭 连接(而不终止 SSE 流),以避免保持长连接。然后,客户端应该通过尝试重新连接来"轮询"SSE 流。
    • 如果服务器确实在终止 _SSE 流_之前关闭 连接,它应该在关闭连接之前发送带有标准 retry 字段的 SSE 事件。客户端必须遵守 retry 字段,在尝试重新连接之前等待给定的毫秒数。
    • SSE 流应该最终包含在 POST 主体中发送的 JSON-RPC _请求_的 JSON-RPC 响应。
    • 服务器可以在发送 JSON-RPC _响应_之前发送 JSON-RPC 请求_和_通知。这些消息应该与原始客户端_请求_相关。
    • 如果会话过期,服务器可以终止 SSE 流。
    • 在发送 JSON-RPC _响应_后,服务器应该终止 SSE 流。
    • 断开连接可能随时发生(例如,由于网络条件)。因此:
      • 断开连接不应该被解释为客户端取消其请求。
      • 要取消,客户端应该显式发送 MCP CancelledNotification。
      • 为了避免由于断开连接而导致消息丢失,服务器可以使流可恢复。

从服务器侦听消息

  1. 客户端可以向 MCP 端点发出 HTTP GET。这可用于打开 SSE 流,允许服务器与客户端通信,而无需客户端首先通过 HTTP POST 发送数据。
  2. 客户端必须包含 Accept 头,将 text/event-stream 列为支持的内容类型。
  3. 服务器必须要么返回 Content-Type: text/event-stream 来响应此 HTTP GET,要么返回 HTTP 405 Method Not Allowed,表示服务器不在此端点提供 SSE 流。
  4. 如果服务器启动 SSE 流:
    • 服务器可以在流上发送 JSON-RPC 请求_和_通知。
    • 这些消息应该与客户端的任何并发运行的 JSON-RPC _请求_无关。
    • 服务器绝不能在流上发送 JSON-RPC 响应,除非正在恢复与先前客户端请求关联的流。
    • 服务器可以随时关闭 SSE 流。
    • 如果服务器在没有终止 _流_的情况下关闭 连接,它应该遵循与 POST 请求相同的轮询行为:发送 retry 字段并允许客户端重新连接。
    • 客户端可以随时关闭 SSE 流。

多个连接

  1. 客户端可以同时保持连接到多个 SSE 流。
  2. 服务器必须仅在其中一个连接的流上发送其每个 JSON-RPC 消息;也就是说,它绝不能在多个流上广播相同的消息。
    • 通过使流可恢复,可以减轻消息丢失的风险。

可恢复性和重新传递

为了支持恢复断开的连接,并重新传递可能丢失的消息:

  1. 服务器可以按照 SSE 标准中的描述向其 SSE 事件附加 id 字段。
    • 如果存在,ID 必须在该会话中的所有流中全局唯一——或者如果未使用会话管理,则在所有具有该特定客户端的流中全局唯一。
    • 事件 ID 应该编码足够的信息以标识发起流,使服务器能够将 Last-Event-ID 关联到正确的流。
  2. 如果客户端希望在断开连接后恢复(无论是由于网络故障还是服务器发起的关闭),它应该向 MCP 端点发出 HTTP GET,并包含Last-Event-ID头以指示它收到的最后一个事件 ID。
    • 服务器可以使用此头重新播放在最后一个事件 ID 之后将在已断开的流上发送的消息,并从该点恢复流。
    • 服务器绝不能重新播放将在不同流上传递的消息。
    • 此机制适用于原始流是如何发起的(通过 POST 或 GET)。恢复始终通过带有 Last-Event-ID 的 HTTP GET 进行。

换句话说,这些事件 ID 应该由服务器在 _每个流_的基础上分配,以充当该特定流中的游标。

会话管理

MCP “会话"由客户端和服务器之间逻辑相关的交互组成,从初始化阶段开始。为了支持希望建立有状态会话的服务器:

  1. 使用可流式 HTTP 传输的服务器可以在初始化时分配会话 ID,通过在包含 InitializeResult 的 HTTP 响应中包含 MCP-Session-Id 头来实现。
    • 会话 ID 应该是全局唯一且加密安全的(例如,安全生成的 UUID、JWT 或加密哈希)。
    • 会话 ID 必须仅包含可见的 ASCII 字符(范围从 0x21 到 0x7E)。
    • 客户端必须以安全方式处理会话 ID,有关更多详细信息,请参阅会话劫持缓解措施。
  2. 如果服务器在初始化期间返回 MCP-Session-Id,则使用可流式 HTTP 传输的客户端必须在其所有后续 HTTP 请求的 MCP-Session-Id 头中包含它。
    • 需要会话 ID 的服务器应该响应没有 MCP-Session-Id 头的请求(初始化除外),并返回 HTTP 400 Bad Request。
  3. 服务器可以随时终止会话,此后它必须响应包含该会话 ID 的请求并返回 HTTP 404 Not Found。
  4. 当客户端收到 HTTP 404 响应于包含 MCP-Session-Id 的请求时,它必须通过发送没有附加会话 ID 的新 InitializeRequest 来启动新会话。
  5. 不再需要特定会话的客户端(例如,因为用户正在离开客户端应用程序)应该向带有 MCP-Session-Id 头的 MCP 端点发送 HTTP DELETE,以显式终止会话。
    • 服务器可以响应此请求并返回 HTTP 405 Method Not Allowed,表示服务器不允许客户端终止会话。

序列图

  sequenceDiagram
    participant Client
    participant Server

    note over Client, Server: 初始化

    Client->>+Server: POST InitializeRequest
    Server->>-Client: InitializeResponse<br>MCP-Session-Id: 1868a90c...

    Client->>+Server: POST InitializedNotification<br>MCP-Session-Id: 1868a90c...
    Server->>-Client: 202 Accepted

    note over Client, Server: 客户端请求
    Client->>+Server: POST ... request ...<br>MCP-Session-Id: 1868a90c...

    alt 单个 HTTP 响应
      Server->>Client: ... response ...
    else 服务器打开 SSE 流
      loop 连接保持打开
          Server-)Client: ... 来自服务器的 SSE 消息 ...
      end
      Server-)Client: SSE 事件:... response ...
    end
    deactivate Server

    note over Client, Server: 客户端通知/响应
    Client->>+Server: POST ... notification/response ...<br>MCP-Session-Id: 1868a90c...
    Server->>-Client: 202 Accepted

    note over Client, Server: 服务器请求
    Client->>+Server: GET<br>MCP-Session-Id: 1868a90c...
    loop 连接保持打开
        Server-)Client: ... 来自服务器的 SSE 消息 ...
    end
    deactivate Server

协议版本头

如果使用 HTTP,客户端必须在所有后续请求中向 MCP 服务器包含 MCP-Protocol-Version: <protocol-version> HTTP 头,允许 MCP 服务器根据 MCP 协议版本进行响应。

例如:MCP-Protocol-Version: 2025-11-25

客户端发送的协议版本应该是在初始化期间协商的版本。

为了向后兼容,如果服务器_未_收到 MCP-Protocol-Version头,并且没有其他方式识别版本——例如,依赖于初始化期间协商的协议版本——服务器应该假设协议版本 2025-03-26。

如果服务器收到具有无效或不支持的 MCP-Protocol-Version 的请求,它必须响应 400 Bad Request。

向后兼容性

客户端和服务器可以维护与已弃用的 HTTP+SSE 传输(来自协议版本 2024-11-05)的向后兼容性,如下所示:

想要支持旧客户端的服务器应该:

  • 继续承载旧传输的 SSE 和 POST 端点,以及为可流式 HTTP 传输定义的新 “MCP 端点”。
    • 也可以将旧的 POST 端点和新的 MCP 端点结合起来,但这可能会引入不必要的复杂性。

想要支持旧服务器的客户端应该:

  1. 从用户接受 MCP 服务器 URL,该 URL 可能指向使用旧传输或新传输的服务器。
  2. 尝试向服务器 URL POST InitializeRequest,并包含如上定义的 Accept 头:
    • 如果成功,客户端可以假设这是支持新可流式 HTTP 传输的服务器。
    • 如果失败并显示以下 HTTP 状态代码 “400 Bad Request”、“404 Not Found” 或 “405 Method Not Allowed”:
      • 向服务器 URL 发出 GET 请求,期望这将打开 SSE 流并返回 endpoint 事件作为第一个事件。
      • 当 endpoint 事件到达时,客户端可以假设这是运行旧 HTTP+SSE 传输的服务器,并应该使用该传输进行所有后续通信。

自定义传输

客户端和服务器可以实现额外的自定义传输机制以满足其特定需求。协议是传输不可知的,可以在任何支持双向消息交换的通信通道上实现。

选择支持自定义传输的实现者必须确保它们保留 MCP 定义的 JSON-RPC 消息格式和生命周期要求。自定义传输应该记录其特定的连接建立和消息交换模式,以帮助互操作性。