订阅 - MCP 中文文档

subscriptions/listen 会从服务器到客户端打开一个长期存在的通知流。与一次性请求不同，该流会保持打开状态并持续发送通知，直到客户端取消它。它取代了原先的 resources/subscribe RPC 和 HTTP GET 端点。

打开流

客户端发送一个带有 notifications 过滤器的 subscriptions/listen 请求，用于指定希望接收哪些事件类型。服务器不得发送客户端未明确请求的通知类型。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscriptions/listen",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "notifications": {
      "toolsListChanged": true,
      "resourceSubscriptions": ["file:///project/config.json"]
    }
  }
}

通知过滤器

字段	类型	描述
`toolsListChanged`	`boolean`	当工具发生变化时接收 `notifications/tools/list_changed`
`promptsListChanged`	`boolean`	当提示词发生变化时接收 `notifications/prompts/list_changed`
`resourcesListChanged`	`boolean`	当列表发生变化时接收 `notifications/resources/list_changed`
`resourceSubscriptions`	`string[]`	为这些资源 URI 接收 `notifications/resources/updated`

所有字段都是可选的。省略某个字段等同于不订阅该通知类型。

确认

服务器必须将 notifications/subscriptions/acknowledged 作为第一条消息发送，并在 _meta 中通过 io.modelcontextprotocol/subscriptionId 携带订阅的 ID，且在此之前不得发送该订阅的任何通知。在 stdio 场景下，所有订阅共享同一通道，这种顺序是按订阅 ID 定义的，而不是按通道定义的：属于其他订阅的消息可以在此之前交错出现。确认响应中的 notifications 字段反映了服务器同意遵守的子集。服务器不支持的通知类型会被省略。

{
  "jsonrpc": "2.0",
  "method": "notifications/subscriptions/acknowledged",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/subscriptionId": 1
    },
    "notifications": {
      "toolsListChanged": true,
      "resourceSubscriptions": ["file:///project/config.json"]
    }
  }
}

客户端应该将已确认的过滤器与其请求内容进行比对，并优雅地处理任何不受支持的类型。

Receiving Notifications

All notifications sent on the stream will carry io.modelcontextprotocol/subscriptionId in _meta, used to identify the subscriptions/listen request that opened the stream. This value is the JSON-RPC ID of the subscriptions/listen request. In the example above, the request used "id": 1, so both the confirmation message and all subsequent notifications will carry subscription ID 1. In stdio, all messages share a single channel, and the client must use this field to associate notifications with their originating subscription.

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/subscriptionId": 1
    },
    "uri": "file:///project/config.json"
  }
}

多个并发订阅

客户端可以同时拥有多个活跃订阅——例如，一个监听工具列表变更，另一个监听资源更新。每个订阅都由其 subscriptions/listen 请求的 JSON-RPC 请求 ID 标识，并且流上的每条通知都会在 io.modelcontextprotocol/subscriptionId 中携带该 ID，以便客户端对它们进行解复用。

取消

订阅在以下情况下结束：

客户端 取消它——关闭 SSE 流（HTTP）或发送 notifications/cancelled，引用 subscriptions/listen 请求 ID（stdio）。
服务器 主动终止它（例如，在关闭期间）——它应该发送空的 subscriptions/listen 响应以表示正常结束（参见优雅关闭），然后关闭流。
底层传输关闭（HTTP 超时、TCP 断开、stdio 进程退出）。

优雅关闭

当服务器主动结束订阅时（例如，在关闭期间），它应该在关闭流之前，先对原始的 subscriptions/listen 请求返回一个空结果。这是对这个长生命周期请求的 JSON-RPC 响应，通过其 id 关联，并表明订阅已优雅结束——而不是突发的传输中断，后者不会携带任何响应。

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "_meta": {
      "io.modelcontextprotocol/subscriptionId": 1
    }
  }
}

与流上的其他消息一样，该响应在 _meta 中携带 io.modelcontextprotocol/subscriptionId，用于标识它关闭的是哪一个订阅。该值与原始 subscriptions/listen 请求的 JSON-RPC id 相匹配。收到此响应的客户端会知道订阅已正常关闭；而没有该响应就关闭的传输则表示一次意外断开，客户端可以将其视为重新连接的触发条件。在 stdio 中，如果连接被终止后又重新建立，客户端必须重新发送 subscriptions/listen 以重新建立其订阅——服务器不会在重连之间保留任何订阅状态。完整规则请参见取消。

基础协议

客户端功能

服务器功能

订阅

打开流

通知过滤器

确认

Receiving Notifications

多个并发订阅

取消

优雅关闭

​打开流

​通知过滤器

​确认

​Receiving Notifications

​多个并发订阅

​取消

​优雅关闭

打开流

通知过滤器

确认

Receiving Notifications

多个并发订阅

取消

优雅关闭