> ## 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.

# 概述

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

模型上下文协议由几个关键组件组成，它们协同工作：

* **基础协议**：核心 JSON-RPC 消息类型
* **版本与兼容性**：协议版本协商、扩展协商，以及与早期协议修订版的互操作性
* **消息模式**：核心协议支持的消息传递模式，包括请求和响应、多轮往返请求（MRTR），以及订阅和通知
* **授权**：用于基于 HTTP 传输的身份验证和授权框架
* **服务器特性**：服务器暴露的资源、提示和工具
* **客户端特性**：客户端提供的提取、采样和根目录列表
* **实用功能**：日志记录和参数补全等横切关注点

所有实现 **必须** 支持基础协议、版本管理和消息模式。其他组件 **可以** 根据应用程序的具体需求进行实现。

这些协议层建立了清晰的关注点分离，同时支持客户端和服务器之间的丰富交互。模块化设计允许实现仅支持它们所需的功能。

## 消息

MCP 客户端和服务器之间的所有消息 **必须** 遵循
[JSON-RPC 2.0](https://www.jsonrpc.org/specification) 规范。协议定义了以下类型的消息：

### 请求

[请求](/specification/draft/schema#jsonrpcrequest) 从客户端发送到服务器，用于发起操作。

```typescript theme={null}
{
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params?: {
    [key: string]: unknown;
  };
}
```

* 请求 **必须** 包含字符串或整数 ID。
* 与基础 JSON-RPC 不同，ID **不得** 为 `null`。
* 请求 ID **不得** 与发送方已发出且尚未收到响应的任何其他请求的 ID 相同。

### 响应

响应作为对请求的回复发送，包含操作的结果或错误。

#### 结果响应

[结果响应](/specification/draft/schema#jsonrpcresultresponse) 在操作成功完成时发送。

```typescript theme={null}
{
  jsonrpc: "2.0";
  id: string | number;
  result: {
    resultType: string;
    [key: string]: unknown;
  };
}
```

* 结果响应 **必须** 包含与其对应请求相同的 ID。
* 结果响应 **必须** 包含 `result` 字段。
* `result` **可以** 采用任何 JSON 对象结构。
* `result` **必须** 包含 `resultType` 字段，以指示结果的类型。

##### 结果类型

结果中的 `resultType` 字段表示所返回结果的类型。MCP 支持多态结果类型，允许服务器根据请求结果返回不同的结构。`resultType` 字段是一个字符串，客户端可以用它来确定如何解析和处理 `result` 对象。

* `resultType` 为 `"complete"` 表示请求已成功完成，结果包含最终内容。
* `resultType` 为 `"input_required"` 表示请求尚未完成，需要更多信息来处理请求。结果包含一个 [`InputRequiredResult`](/specification/draft/basic/patterns/mrtr#inputrequiredresult) 对象，其中包含所需的附加信息。
* 扩展 **可以** 添加额外的 `ResultType` 值。支持的 `ResultType` 值集合 **必须** 由核心协议中定义的集合以及通过能力声明的任何受支持扩展的附加值共同构成。
* 客户端无法识别的任何 `ResultType` 值 **必须** 被视为无效。
* 为了与实现早期协议版本且不包含 `resultType` 的服务器保持向后兼容，客户端 **必须** 将缺失的 `resultType` 视为 `"complete"`。

#### 错误响应

[错误响应](/specification/draft/schema#jsonrpcerrorresponse) 在操作失败或遇到错误时发送。

```typescript theme={null}
{
  jsonrpc: "2.0";
  id?: string | number;
  error: {
    code: number;
    message: string;
    data?: unknown;
  }
}
```

* 错误响应 **必须** 包含与其对应请求相同的 ID（除非在因请求格式错误而无法读取 ID 的错误情况下）。
* 错误响应 **必须** 包含带有 `code` 和 `message` 的 `error` 字段。
* 错误代码 **必须** 是整数。

#### 错误代码

MCP 使用标准的 JSON-RPC 2.0 错误代码（`-32700`、`-32600` 到 `-32603`）
表示一般协议失败。

JSON-RPC 2.0 保留了 `-32000` 到 `-32099` 的范围用于实现定义的
服务器错误。MCP 对该范围作如下划分：

* **`-32000` 到 `-32019` — 旧版。** 该子范围中的代码是在
  本策略引入之前由实现分配的。新的代码 **不得** 分配到
  此子范围，而新的实现 **不应** 使用此子范围中的代码。
  除了 `-32002`（见下文）之外，接收方
  **不得** 假定这些代码具有任何特定含义。
* **`-32020` 到 `-32099` — 保留给 MCP 规范。** 该子范围中的错误代码
  仅由 MCP 规范定义并记录在 [schema](/specification/draft/schema) 中。实现
  **不得** 发出任何本规范未定义的该子范围内的代码，并且 **必须**
  仅以其指定含义使用已定义的代码。

MCP 定义了以下错误代码：

| 代码       | 名称                                                                                                    |
| -------- | ----------------------------------------------------------------------------------------------------- |
| `-32020` | [`HeaderMismatch`](/specification/draft/schema#headermismatcherror)                                   |
| `-32021` | [`MissingRequiredClientCapability`](/specification/draft/schema#missingrequiredclientcapabilityerror) |
| `-32022` | [`UnsupportedProtocolVersion`](/specification/draft/schema#unsupportedprotocolversionerror)           |

早期协议版本定义的代码仍然保留，不会被重复使用。此协议版本的实现 **不得** 发出这些代码：

* `-32002` — 未找到资源（2025-11-25 及更早版本；已由 `-32602` 取代）。
  客户端 [**应该** 仍接受 `-32002`](/specification/draft/server/resources#error-handling) 来自实现早期版本的服务器。
* `-32042` — 需要 URL 提供（仅限 2025-11-25）。

纯粹属于实现本地的错误（例如，在 SDK 内部引发的请求超时）目前未由本规范分配代码。将本地错误以 JSON-RPC 形式结构暴露的实现应确保它们不会被误认为是从对端接收到的错误。未来版本的规范可能会在保留子范围内为常见的本地错误条件定义标准代码。

对于本规范未定义用途的新错误代码，**应该** 分配在 JSON-RPC 保留范围（`-32768` 到 `-32000`）之外；其余整数空间可用于应用定义的错误。

### 通知

[通知](/specification/draft/schema#jsonrpcnotification) 由客户端发送给服务器，反之亦然，作为单向消息。接收者 **不得** 发送响应。

```typescript theme={null}
{
  jsonrpc: "2.0";
  method: string;
  params?: {
    [key: string]: unknown;
  };
}
```

* 通知 **不得** 包含 ID。

### 消息模式

模型上下文协议（MCP）支持若干种[消息模式](/specification/draft/basic/patterns)，用于定义客户端与服务器如何交互：

1. **[请求和响应](/specification/draft/basic/patterns#request-and-response)**：客户端向服务器发送请求，服务器以结果或错误进行响应。
2. **[多轮往返请求（MRTR）](/specification/draft/basic/patterns#multi-round-trip-requests)**：服务器需要额外的客户端输入（采样、提取或根）才能完成请求。
3. **[订阅和通知](/specification/draft/basic/patterns#subscribe-and-notify)**：客户端订阅来自服务器的通知流，通知会在发生时发送。

## 无状态性

模型上下文协议（MCP）是一个**无状态协议**：处理请求所需的所有信息都包含在请求本身中。服务器独立处理每个请求；不应从先前的请求中推断状态，即使这些请求来自同一连接或流。

具体而言：

* 服务器 **不得** 依赖同一连接上的先前请求来建立上下文（例如，能力、协议版本、客户端身份）。
  每个请求都在其 [`_meta`](#meta) 字段中提供这些元数据。
* 服务器 **应该** 能够处理与多个任务、线程或会话相关的请求。
* 服务器 **不应** 要求客户端复用相同的连接或进程来执行相关操作。
* 客户端 **不应** 将单个任务、线程或会话作为 stdio 进程的生命周期边界。
* 需要跨多个请求存在的状态（例如，长时间运行的任务、应用级句柄）**必须** 通过客户端在每个请求中传递的显式标识符来引用。

<Note>
  这意味着，像 STDIO 进程这样的打开连接并不是一次对话或会话：客户端可以在同一传输上交错发送无关请求，而服务器不得将连接或进程身份视为对话或会话连续性的替代。
</Note>

像
[`subscriptions/listen`](/specification/draft/basic/patterns/subscriptions) 这样的长生命周期请求仍然是请求/响应模式；响应只是一个开放的通知流。其状态作用域限定于请求本身，而不是底层连接。

<Info>
  关于请求级模型如何映射到 SDK 代码的演练，请参阅
  [架构指南](/docs/learn/architecture#example)。
</Info>

## 授权

MCP 提供了一个用于 HTTP 的[授权](/specification/draft/basic/authorization)框架。
使用基于 HTTP 传输的实现 **应该** 符合此规范，
而使用 STDIO 传输的实现 **不应该** 遵循此规范，
而是从环境中检索凭据。

此外，客户端和服务器 **可以** 协商它们自己的自定义认证和授权策略。

如需进一步讨论并为 MCP 认证机制的发展做出贡献，请加入
[GitHub 讨论区](https://github.com/modelcontextprotocol/specification/discussions)
来帮助塑造协议的未来！

## 模式

协议的完整规范定义为
[TypeScript 模式](https://github.com/modelcontextprotocol/specification/blob/main/schema/draft/schema.ts)。
这是所有协议消息和结构的真实来源。

还有一个
[JSON Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/draft/schema.json)，
它是从 TypeScript 真实来源自动生成的，用于
各种自动化工具。

## JSON Schema 用法

模型上下文协议在整个协议中使用 JSON Schema 进行验证。本节阐明了如何在 MCP 消息中使用 JSON Schema。

### 模式方言

MCP 支持带有以下规则的 JSON Schema：

1. **默认方言**：当模式不包含 `$schema` 字段时，默认为 [JSON Schema 2020-12](https://json-schema.org/draft/2020-12/schema)
2. **显式方言**：模式 **可以** 包含 `$schema` 字段以指定不同的方言
3. **支持的方言**：实现 **必须** 至少支持 2020-12 并 **应该** 记录它们支持哪些其他方言
4. **建议**：建议实现者使用 JSON Schema 2020-12。

### 用法示例

#### 默认方言 (2020-12):

```json theme={null}
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}
```

#### 显式方言 (draft-07):

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}
```

### 实现要求

* 客户端和服务器 **必须** 支持没有显式 `$schema` 字段的模式的 JSON Schema 2020-12
* 客户端和服务器 **必须** 根据其声明的或默认的方言验证模式。他们 **必须** 优雅地处理不支持的方言，返回适当的错误表明该方言不受支持。
* 客户端和服务器 **应该** 记录它们支持哪些模式方言

### 模式验证

* 模式 **必须** 根据其声明的或默认的方言有效

### `$ref` 解析

JSON Schema 2020-12 允许 `$ref` 指向绝对 URI。实现 **不得**
自动解析会解析到网络 URI 的 `$ref` 值。

实现 **可以** 提供可选模式以获取非本地 `$ref`，但该模式
**必须** 默认禁用，并且 **应该** 强制执行主机允许列表，或者至少拒绝回环、本地链路和私有网络地址，应用超时和
大小限制，并记录已解析的 URI。

由于未解析的外部 `$ref` 导致验证失败的模式 **应该** 被拒绝，
而不是静默地视为宽松通过。

### 组合关键字资源使用

组合关键字（`anyOf`、`oneOf`、`allOf`、`if`/`then`/`else`）和 `$defs` 支持
表达能力强的模式，但验证成本可能很高。实现 **应该** 应用合理的限制，例如最大模式深度、子模式总数上限，
或者每次验证的时间预算，以防止恶意模式成为针对验证器的拒绝服务
向量。

## 通用字段

### `_meta`

`_meta` 属性/参数由 MCP 保留，允许客户端和服务器
在其交互中附加额外的元数据。

某些键名由 MCP 保留用于协议级元数据，如下所示；
实现 **不得** 对这些键处的值做出假设。

此外，[模式](https://github.com/modelcontextprotocol/specification/blob/main/schema/draft/schema.ts) 中的定义
可能会为特定用途的元数据保留特定名称，如这些定义中所述。

**键名格式：** 有效的 `_meta` 键名有两个部分：一个可选的 **前缀** 和一个 **名称**。

**前缀：**

* 如果指定，**必须** 是一系列由点 (`.`) 分隔的标签，后跟斜杠 (`/`)。
  * 标签 **必须** 以字母开头，以字母或数字结尾；内部字符可以是字母、数字或连字符 (`-`)。
  * 实现 **应该** 使用反向 DNS 表示法（例如，`com.example/` 而不是 `example.com/`）。
* 任何第二个标签是 `modelcontextprotocol` 或 `mcp` 的前缀均 **保留** 供 MCP 使用。
  * 例如：`io.modelcontextprotocol/`、`dev.mcp/`、`org.modelcontextprotocol.api/` 和 `com.mcp.tools/` 均被保留。
  * 但是，`com.example.mcp/` 未被保留，因为第二个标签是 `example`。

**名称：**

* 除非为空，否则 **必须** 以字母数字字符 (`[a-z0-9A-Z]`) 开头和结尾。
* 中间 **可以** 包含连字符 (`-`)、下划线 (`_`)、点 (`.`) 和字母数字字符。

**每请求协议字段：**

每个客户端请求在 `_meta` 中 **必须** 包含以下 `io.modelcontextprotocol/*` 字段。服务器使用这些字段在不依赖任何先前连接状态的情况下识别客户端和正在使用的协议版本。版本协商规则请参见[版本与兼容性][lifecycle]。

| 键                                            | 类型                   | 必需 | 描述                          |
| -------------------------------------------- | -------------------- | -- | --------------------------- |
| `io.modelcontextprotocol/protocolVersion`    | `string`             | 是  | 此请求的协议版本（例如，`"2026-07-28"`） |
| `io.modelcontextprotocol/clientInfo`         | `Implementation`     | 是  | 客户端名称和版本                    |
| `io.modelcontextprotocol/clientCapabilities` | `ClientCapabilities` | 是  | 与此请求相关的客户端能力                |
| `io.modelcontextprotocol/logLevel`           | `LoggingLevel`       | 否  | 服务器应为此请求发出的最低日志级别           |

缺少任何必需字段的请求都属于格式错误；服务器 **必须** 使用
JSON-RPC 错误码 `-32602`（无效参数）拒绝它。在 HTTP 上，响应状态 **必须** 为
`400 Bad Request`。

服务器 **不得** 依赖客户端未声明的能力。如果处理请求需要某个客户端未在
`io.modelcontextprotocol/clientCapabilities` 中包含的能力，服务器 **必须** 返回
[`MissingRequiredClientCapabilityError`](/specification/draft/schema#missingrequiredclientcapabilityerror)
（`-32021`），其 `data.requiredCapabilities` 列出缺失的能力。在
HTTP 上，响应状态 **必须** 为 `400 Bad Request`。

对于通过 [`subscriptions/listen`][subscriptions-listen] 流传递的通知，服务器
**必须** 在 `_meta` 中包含 `io.modelcontextprotocol/subscriptionId`，以便
客户端可以将通知与源订阅请求关联起来。

[lifecycle]: /specification/draft/basic/versioning

[subscriptions-listen]: /specification/draft/basic/patterns/subscriptions

**OpenTelemetry 追踪上下文：**

作为对上述前缀要求的例外，键 `traceparent`、`tracestate` 和
`baggage` 保留用于 [OpenTelemetry](https://opentelemetry.io/) 追踪上下文传播。
当存在时，它们的值 **必须** 分别遵循 [W3C 追踪上下文](https://www.w3.org/TR/trace-context/)
和 [W3C Baggage](https://www.w3.org/TR/baggage/) 格式。

此例外存在是为了与现有实现和
[MCP 的 OpenTelemetry 语义约定](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/) 保持兼容。

`_meta` 中追踪上下文的非规范性示例：

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "New York"
    },
    "_meta": {
      "traceparent": "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
    }
  }
}
```

### `icons`

`icons` 属性为服务器提供了一种标准化方式来暴露其资源、工具、提示和实现的视觉标识。图标通过提供视觉上下文和提高可用功能的可发现性来增强用户界面。

图标表示为 `Icon` 对象数组，其中每个图标包括：

* `src`：指向图标资源的 URI（必需）。这可以是：
  * 指向图像文件的 HTTP/HTTPS URL
  * 带有 base64 编码图像数据的 data URI
* `mimeType`：如果服务器的类型缺失或通用，则为可选的 MIME 类型
* `sizes`：可选的尺寸规格数组（例如，`["48x48"]`、`["any"]` 用于 SVG 等可缩放格式，或 `["48x48", "96x96"]` 用于多种尺寸）
* `theme`：图标背景的可选主题偏好（`light` 或 `dark`）

**必需的 MIME 类型支持：**

支持渲染图标的客户端 **必须** 至少支持以下 MIME 类型：

* `image/png` - PNG 图像（安全，通用兼容）
* `image/jpeg`（和 `image/jpg`）- JPEG 图像（安全，通用兼容）

支持渲染图标的客户端 **应该** 也支持：

* `image/svg+xml` - SVG 图像（可缩放，但需要如下所述的安全预防措施）
* `image/webp` - WebP 图像（现代，高效格式）

**安全考虑：**

图标元数据的消费者 **必须** 在处理图标时采取适当的安全预防措施以防止泄露：

* 将图标元数据和图标字节视为不可信的输入，并防御网络、隐私和解析风险。
* 确保图标 URI 是 HTTPS 或 `data:` URI。客户端 **必须** 拒绝使用不安全方案和重定向的图标 URI，例如 `javascript:`、`file:`、`ftp:`、`ws:` 或本地应用 URI 方案。
  * 禁止方案更改和重定向到不同源的主机。
* 对源自过大图像、大尺寸或过多帧（例如在 GIF 中）的资源耗尽攻击具有弹性。
  * 消费者 **可以** 为图像和内容大小设置限制。
* 获取图标时不带凭据。不要发送 cookie、`Authorization` 头或客户端凭据。
* 验证图标 URI 是否与服务器同源。这最小化了向第三方暴露数据或追踪信息的风险。
* 在获取和渲染图标时要小心，因为负载 **可能** 包含可执行内容（例如带有 [嵌入式 JavaScript](https://www.w3.org/TR/SVG11/script.html) 或 [扩展功能](https://www.w3.org/TR/SVG11/extend.html) 的 SVG）。
  * 消费者 **可以** 选择禁止特定文件类型或在渲染前清理图标文件。
* 在渲染前验证 MIME 类型和文件内容。将 MIME 类型信息视为建议性的。通过魔术字节检测内容类型；在不匹配或未知类型时拒绝。
  * 维护严格的图像类型允许列表。

**用法：**

图标可以附加到：

* `Implementation`：MCP 服务器/客户端实现的视觉标识
* `Tool`：工具功能的视觉表示
* `Prompt`：与提示模板一起显示的图标
* `Resource`：不同资源类型的视觉指示器

可以提供多个图标以支持不同的显示上下文和分辨率。客户端应根据其 UI 需求选择最合适的图标。