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

# 协议时代

> Inspector 如何协商传统版与现代版 MCP，以及每项功能如何在不同协议时代之间处理

MCP 在 2026-07-28 的修订中对协议进行了重大更改。因此，Inspector 将**协议时代**（传统版或现代版，即该修订之前或自该修订起）视为一项一等的、按服务器设置的配置，并将其与传输方式正交处理：同一个 HTTP URL 可以作为传统版服务器或现代版服务器进行检查。根据当前所采用的协议时代，多个选项卡会呈现出有意义差异的 UI 和流量。

## `Protocol Era` 设置

每个服务器都具有 `legacy`、`auto` 或 `modern` 三种状态之一的 `protocolEra`。在 Web 客户端中，它位于 **服务器设置**；在目录或配置文件中，它是 `protocolEra` 字段；在 CLI 和 TUI 中，它来自同一个文件。

| 状态       | 检查器在连接时执行的操作                                       |
| -------- | -------------------------------------------------- |
| `legacy` | **默认值。** 使用普通的 `initialize`，完全不进行探测。               |
| `auto`   | 首先探测 `server/discover`，遇到任何非现代结果时回退到 `initialize`。 |
| `modern` | 精确固定为 `2026-07-28`。不进行回退，因此非现代服务器会明确报错。            |

<Note>
  **为什么默认值是 `legacy`，而不是 `auto`。** 调试工具不应自动探测。对无响应的旧版 stdio 服务器进行 `server/discover` 探测会一直停滞，而且会污染你来此查看的记录会话。选择 `auto` 或 `modern` 是一个有意的操作，因此你在协议选项卡中看到的内容，就是服务器在客户端按照你所配置的方式运行时所看到的内容。
</Note>

三种客户端中的状态选择方式完全相同。

连接后，协商出的状态会显示在连接标头和 **连接信息** 中。在现代连接上，`server/discover` 还会提供 `capabilities`（包括 `extensions`）、`instructions` 以及 `supportedVersions` 列表。服务器的名称和版本会出现在结果 `_meta` 下的 `io.modelcontextprotocol/serverInfo` 中。

<Frame caption="服务器设置：Protocol Era 选择器，包含全部三种选项。">
  <img src="https://mintcdn.com/mcp-zhcndoc/g9OY95jIBkKJGM1n/images/inspector/settings-protocol-era.png?fit=max&auto=format&n=g9OY95jIBkKJGM1n&q=85&s=9f7c64e3ffe02acefcb775b157275a46" width="3840" height="2160" data-path="images/inspector/settings-protocol-era.png" />
</Frame>

## 在本地复现各个时代

下面的每个部分末尾都包含一个 **使用……复现** 的指引，指向 Inspector 仓库中随附的某个 **可组合测试服务器** 的 JSON 配置。克隆仓库、构建测试服务器，然后让 Inspector 指向该部分所指定的配置。

```bash theme={null}
git clone https://github.com/modelcontextprotocol/inspector
cd inspector && npm install && npm run build
cd clients/web && npm run test-servers:build
```

***

## 日志

<Tabs>
  <Tab title="旧版">
    日志是**会话范围的**。客户端发送一次 `logging/setLevel`，在该会话的剩余时间内，服务器会发出达到该级别或更高级别的 `notifications/message`。

    **日志**选项卡显示一个**设置活动级别**选择器和一个**设置**按钮。选择级别，点击“设置”，之后的服务器日志就会流入面板。

    使用 `test-servers/configs/logging-legacy-http.json` 重现。
  </Tab>

  <Tab title="现代版">
    `logging/setLevel` 已被**移除**。取而代之的是，客户端通过在每个发出的请求上添加 `_meta["io.modelcontextprotocol/logLevel"]` 来**按请求选择加入**。对于未选择加入的请求，服务器**不得**发出 `notifications/message`。

    因此，**日志**选项卡现在显示的是**每个请求的日志级别**控件。选择一个级别，之后的每个请求都会携带该标记，并且可以在“网络”选项卡的请求正文中看到。处理请求时产生的日志会随该请求的 SSE 响应流传输。

    将控件设置为**关闭**后，`logLevel` 键会被完全省略，因此同一个工具调用将完全不会产生日志。这种静默是正确行为，而不是错误。

    每个服务器的默认级别是 `debug`（默认选择最详细的级别，因为 Inspector 是一个调试工具）；在服务器上设置 `modernLogLevel: "off"`，即可默认选择退出。

    使用 `test-servers/configs/logging-modern-http.json` 重现。
  </Tab>
</Tabs>

<Frame caption="旧版：日志选项卡提供了一个会话范围的“设置活动级别”控件，调用 send_notification 后会收到一条日志。">
  <img src="https://mintcdn.com/mcp-zhcndoc/g9OY95jIBkKJGM1n/images/inspector/logs-legacy.png?fit=max&auto=format&n=g9OY95jIBkKJGM1n&q=85&s=bd3b8ce7dd896d81a50177fcb797b892" width="3840" height="2160" data-path="images/inspector/logs-legacy.png" />
</Frame>

<Frame caption="现代版：同一选项卡改为提供“每个请求的日志级别”。该级别会添加到每个发出的请求上，并且日志会随该请求的流传输。">
  <img src="https://mintcdn.com/mcp-zhcndoc/g9OY95jIBkKJGM1n/images/inspector/logs-modern.png?fit=max&auto=format&n=g9OY95jIBkKJGM1n&q=85&s=560e2471f80113095e4da7129e337413" width="3840" height="2160" data-path="images/inspector/logs-modern.png" />
</Frame>

***

## 资源订阅

<Tabs>
  <Tab title="旧版">
    点击资源上的 **订阅** 会发送 `resources/subscribe`。订阅部分会列出 URI，不显示流控件。当资源发生变化时，服务器会发出 `notifications/resources/updated`，并为已订阅磁贴标记最近更新时间。

    使用 `test-servers/configs/subscriptions-legacy-http.json` 进行复现，该配置还提供了一个 `update_resource` 工具，因此你可以自行驱动通知往返流程。
  </Tab>

  <Tab title="现代版">
    相同的 **订阅** 按钮现在会发送 **`subscriptions/listen`**，并携带包含 `resourceSubscriptions` 以及 `resourcesListChanged` opt-in 的筛选器。当服务器发送 `notifications/subscriptions/acknowledged` 时，订阅即得到确认。

    由于订阅现在是长期流，而不再是会话标志，订阅部分的标题中增加了一个 **流状态徽章**，状态会从 `Connecting...` 变为 `Listening`。如果流断开，Inspector 会通过重新发送 `subscriptions/listen` 来重新连接。

    使用 `test-servers/configs/subscriptions-modern-http.json` 进行复现。
  </Tab>
</Tabs>

<Frame caption="一个现代版订阅：订阅部分带有 LISTENING 流状态徽章，而旧版订阅无需此徽章。">
  <img src="https://mintcdn.com/mcp-zhcndoc/g9OY95jIBkKJGM1n/images/inspector/resources-subscriptions-modern.png?fit=max&auto=format&n=g9OY95jIBkKJGM1n&q=85&s=25a91303b0d426a4284030f10cb6ae0f" width="3840" height="2160" data-path="images/inspector/resources-subscriptions-modern.png" />
</Frame>

***

## 任务

任务在不同协议时代之间变化最大，包括 *Inspector UI 标签页如何受控*。

<Tabs>
  <Tab title="旧版">
    当服务器声明 `capabilities.tasks` 时，会显示 **任务** 标签页。启用 **作为任务运行** 后运行工具，该标签页会列出该工具，通过 `tasks/list` 填充列表，并使用 `tasks/get` 进行轮询。已完成的负载通过**阻塞式 `tasks/result`**获取，而**取消**操作会发送 `tasks/cancel`。

    使用 `test-servers/configs/tasks-legacy-http.json` 复现。
  </Tab>

  <Tab title="现代版">
    任务是一项**扩展**（`io.modelcontextprotocol/tasks`，[SEP-2663](/seps/2663-tasks-extension)），因此标签页取决于\_已协商的扩展\_，而不是 `capabilities.tasks`。

    将工具作为任务运行，`tools/call` 会返回一个 `CreateTaskResult`（`resultType: "task"`，可在协议和网络标签页中看到）。Inspector 只轮询 **`tasks/get`**；不存在 `tasks/list`，因此**刷新**会重新轮询客户端已知的句柄。已完成的任务会**内联其结果**，不会调用阻塞式 `tasks/result`。

    需要更多信息的任务会转为 `input_required`，并在待处理请求模态框中显示嵌入式[引导](/specification/draft/client/elicitation)（即 Web 客户端在请求等待你的响应时打开的对话框）。回答后会发送携带 `inputResponses` 的 **`tasks/update`**，下一次轮询将完成任务。

    使用 `test-servers/configs/tasks-modern-http.json`（工具 `modern_task` 和 `modern_input_task`）复现。
  </Tab>
</Tabs>

<Frame caption="旧版：任务标签页通过 tasks/list 填充，负载通过阻塞式 tasks/result 获取。">
  <img src="https://mintcdn.com/mcp-zhcndoc/g9OY95jIBkKJGM1n/images/inspector/tasks-legacy.png?fit=max&auto=format&n=g9OY95jIBkKJGM1n&q=85&s=31a4458f76628d0b581c5a6e8a3eb0ed" width="3840" height="2160" data-path="images/inspector/tasks-legacy.png" />
</Frame>

<Frame caption="现代版：客户端轮询其已持有句柄对应的 tasks/get，已完成的任务会内联其结果；请注意完整任务对象中的 resultType: complete。">
  <img src="https://mintcdn.com/mcp-zhcndoc/g9OY95jIBkKJGM1n/images/inspector/tasks-modern.png?fit=max&auto=format&n=g9OY95jIBkKJGM1n&q=85&s=fba998d8bc2de89240ba738434c7ebce" width="3840" height="2160" data-path="images/inspector/tasks-modern.png" />
</Frame>

***

## 多轮工具结果（MRTR）

在现代时代，工具可以返回 `input_required` 而不是最终结果，并嵌入一个 [elicitation](/specification/draft/client/elicitation)、[sampling](/specification/draft/client/sampling) 请求，或 [`roots/list`](/specification/draft/client/roots) 请求。客户端回答该嵌入请求后，会在新的 JSON-RPC id 下重试 `tools/call`，直到调用达到 `complete` 状态。

Inspector 手动驱动 MRTR，因此每一轮都会暂停在标记为 `input_required` 的**待处理请求模态框**中，等待你回答。Protocol 视图会将整个交互归为一个 MRTR 会话，而不是彼此无关的调用。

`test-servers/configs/mrtr-showcase-http.json` 将现代服务器中的所有形态集中在一起：

| 工具              | 测试内容                                               |
| --------------- | -------------------------------------------------- |
| `mrtr_confirm`  | 单轮 elicitation。                                    |
| `mrtr_two_step` | 两轮 elicitation，通过 `requestState` 串联。               |
| `mrtr_sample`   | 嵌入式 sampling 请求，路由至 Sampling 面板。                   |
| `mrtr_roots`    | 嵌入式 `roots/list`，从已配置的根目录静默回答（无模态框）。               |
| `mrtr_edge`     | 仅包含 `inputRequests` 的一轮，然后是仅包含 `requestState` 的一轮。 |
| `mrtr_loop`     | 永不完成，因此客户端会在达到 `MRTR_MAX_ROUNDS` 限制时停止。            |

<Note>
  旧版的 `collect_elicitation` 模式（服务器调用
  `server.elicitInput`）在 2026-07-28 的连接上会**报错**，因为此时不允许服务器向客户端发送请求。MRTR 是其现代替代方案。
</Note>

<Frame caption="一个 MRTR 轮次暂停在标记为 input_required 的待处理请求模态框中。回答后会重试原始请求。">
  <img src="https://mintcdn.com/mcp-zhcndoc/g9OY95jIBkKJGM1n/images/inspector/mrtr-pending-request.png?fit=max&auto=format&n=g9OY95jIBkKJGM1n&q=85&s=5eb8cfdc17ece95f0a3bfb94faee97ee" width="3840" height="2160" data-path="images/inspector/mrtr-pending-request.png" />
</Frame>

***

## 工具：镜像请求头和排除的工具

[SEP-2243](/seps/2243-http-standardization) 允许工具使用 `x-mcp-header` 标注参数，请求 Streamable HTTP 客户端将该参数的值镜像到 `Mcp-Param-*` 请求头中。

Inspector 会在 **工具** 标签页中展示该契约的两部分：

* 带有**有效**标注的工具，会在其详情面板中显示 **“镜像请求头（SEP-2243）”** 部分，例如 `city -> Mcp-Param-City`。
* 带有**无效**标注的工具（例如请求头名称为 `"Bad Header"`，其中的空格使其成为无效的 RFC 9110 token）会在侧边栏的 **“已排除（SEP-2243）”** 分隔线下以删除线显示，悬停时可查看原因。符合规范的客户端必须从 `tools/list` 中删除此类工具；Inspector 会显示工具被删除的原因，而不是静默地将其隐藏。

使用 `test-servers/configs/xmcpheader-modern-http.json` 重现。

<Warning>
  **SDK 在浏览器中会跳过 `Mcp-Param-*` 镜像。** 从*网页*客户端调用镜像工具时会省略该请求头，因此严格的服务器会返回 `-32020`（`HeaderMismatch`，请参见下面的[网络和协议请求头与错误分类](#network-and-protocol-headers-and-the-error-taxonomy)）。从 **CLI** 或 **TUI** 调用同一工具时，由于二者都运行在 Node 上，因此会正确进行镜像。该请求头由 SDK 内部的环境检查丢弃，不受 Inspector 控制。
</Warning>

<Frame caption="get_weather 显示其镜像的 city -> Mcp-Param-City 请求头，而 invalid_header_tool 则在“已排除（SEP-2243）”分隔线下以删除线显示。">
  <img src="https://mintcdn.com/mcp-zhcndoc/g9OY95jIBkKJGM1n/images/inspector/tools-sep2243.png?fit=max&auto=format&n=g9OY95jIBkKJGM1n&q=85&s=e66ab67fd62aa8fc52b8ab0902b60c79" width="3840" height="2160" data-path="images/inspector/tools-sep2243.png" />
</Frame>

### `-32602` 错误面板

在现代时代，返回 `-32602` 的 `tools/call` 会以独立的**错误面板**呈现：

* **未知工具**：当消息中指定的工具未被服务器列出时。调用服务器 `tools/list` 中不存在的任意名称即可重现。
* **无效参数**：其他任何 `-32602` 错误。使用上述配置中的 `trigger_invalid_params` 工具即可重现。

两个时代都会以 `-32602` 拒绝请求；变化的只有 Inspector 的呈现方式。在旧版连接上，你会得到一个通用的 JSON-RPC 失败响应，必须阅读消息才能判断遇到的是哪种情况。

***

## 网络与协议：标头和错误分类

现代规范统一了一组 `Mcp-*` HTTP 标头，并引入了更丰富的 JSON-RPC 错误分类（[SEP-2243](/seps/2243-http-standardization) / [SEP-2575](/seps/2575-stateless-mcp)）。两个监控选项卡分工如下：

* **网络**选项卡是 HTTP 视图：镜像的 `Mcp-*` 标头会突出显示，并对哨兵值进行解码。
* **协议**选项卡是 JSON-RPC 视图：每种规范错误都会单独呈现，而不是显示为通用失败。

`test-servers/configs/modern-network-http.json` 提供四个工具，每个工具对应一种错误类别，并会生成真实的 HTTP 状态和 JSON-RPC 错误正文：

| 工具                            | HTTP  | JSON-RPC 代码 | 含义                                 |
| ----------------------------- | ----- | ----------- | ---------------------------------- |
| `trigger_header_mismatch`     | `400` | `-32020`    | 缺少必需的镜像标头，或标头值不正确。                 |
| `trigger_missing_capability`  | `400` | `-32021`    | 请求中缺少服务器所需的客户端能力。                  |
| `trigger_unsupported_version` | `400` | `-32022`    | 版本不受支持；支持的版本位于 `data.supported` 中。 |
| `trigger_method_not_found`    | `404` | `-32601`    | 找不到方法。                             |

<Frame caption="网络选项卡显示 HTTP 层；此处显示的是严格服务器返回的 400 Bad Request。">
  <img src="https://mintcdn.com/mcp-zhcndoc/g9OY95jIBkKJGM1n/images/inspector/network-modern-headers.png?fit=max&auto=format&n=g9OY95jIBkKJGM1n&q=85&s=5625d0909ef3645e8fbddebc8ccec65b" width="3840" height="2160" data-path="images/inspector/network-modern-headers.png" />
</Frame>

<Frame caption="协议选项卡将同一失败呈现为类型化规范错误：-32022 UnsupportedProtocolVersion，并显示服务器支持的版本。">
  <img src="https://mintcdn.com/mcp-zhcndoc/g9OY95jIBkKJGM1n/images/inspector/protocol-modern-error.png?fit=max&auto=format&n=g9OY95jIBkKJGM1n&q=85&s=4dde663c8fb725f5f68250fc70505c62" width="3840" height="2160" data-path="images/inspector/protocol-modern-error.png" />
</Frame>

***

## 会话

传统的 Streamable HTTP 连接可能携带服务器分配的会话 ID（`Mcp-Session-Id`），客户端通过 HTTP `DELETE` 将其拆除。现代连接是**无会话且按请求建立的**：在没有会话 ID 时，客户端 SDK 不会向服务器发送 `DELETE`，因此断开连接完全是本地操作。

这对你自己的测试服务器有一个实际影响。每次请求构造的无状态现代处理程序无法在调用之间保存状态，这也是为什么 `test-servers/configs/subscriptions-modern-http.json` 不同于其传统版本，没有包含 `update_resource` 工具：该变更会针对一个用完即弃的服务器实例运行，后续读取时将无法看到这一变更。