> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.developerdoc.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 订阅

<div id="enable-section-numbers" />

`subscriptions/listen` 打开一个从服务器到客户端的长生命周期通知流。
与一次性请求不同，该流会保持打开并交付通知，直到客户端取消它。
它替代了以前的 `resources/subscribe` RPC 和 HTTP GET 端点。

## 打开流

客户端发送带有 `notifications` 过滤器的 `subscriptions/listen` 请求，
指定它想接收的事件类型。服务器 **MUST NOT** 发送客户端未明确请求的通知类型。

```json theme={null}
{
  "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` |

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

## 确认

服务器 **MUST** 将 `notifications/subscriptions/acknowledged` 作为流上的第一条消息发送。
确认中的 `notifications` 字段反映服务器同意履行的子集；服务器不支持的通知类型会被省略。

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

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

## 接收通知

流上交付的所有通知都会在 `_meta` 中携带 `io.modelcontextprotocol/subscriptionId`，
该值与打开流的 `subscriptions/listen` 请求 ID 匹配。在 stdio 上，所有消息共享单一通道，
客户端 **MUST** 使用此字段将通知与其来源订阅相关联。

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

## 多个并发订阅

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

## 取消

订阅会在以下情况下结束：

* **客户端**取消订阅：关闭 SSE 流（HTTP），或发送引用 `subscriptions/listen` 请求 ID 的
  `notifications/cancelled`（stdio）。
* **服务器**将其拆除（例如在关闭期间）：它 **MUST** 关闭 SSE 流（HTTP），或发送引用
  `subscriptions/listen` 请求 ID 的 `notifications/cancelled`（stdio）。
* 底层传输关闭（HTTP 超时、TCP 断开、stdio 进程退出）。

在 **stdio** 上，如果连接终止后又重新建立，客户端 **MUST** 重新发送 `subscriptions/listen`
以重新建立订阅；服务器不会在重连之间保留任何订阅状态。

完整规则见[取消][cancellation]。

[cancellation]: /specification/draft/basic/patterns/cancellation