> ## 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" />

Model Context Protocol 由几个协同工作的关键组件组成：

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

所有实现 **MUST** 支持基础协议、版本管理和消息模式。其他组件 **MAY** 根据应用的具体需求实现。

这些协议层建立了清晰的关注点分离，同时支持客户端与服务器之间的丰富交互。
模块化设计允许实现只支持其实际需要的特性。

## Messages

MCP 客户端与服务器之间的所有消息 **MUST** 遵循
[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;
  };
}
```

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

### Responses

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

#### 结果响应

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

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

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

##### ResultType

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

* `resultType` 为 `"complete"` 表示请求已成功完成，且结果包含最终内容。
* `resultType` 为 `"input_required"` 表示请求尚未完成，需要更多信息才能处理该请求。结果包含一个 [`InputRequiredResult`](/specification/draft/basic/patterns/mrtr#inputrequiredresult) 对象，其中带有所需的额外信息。
* 扩展 **MAY** 添加额外的 `ResultType` 值。受支持的 `ResultType` 值集合 **MUST** 基于核心协议定义的集合创建，并包含通过能力声明的受支持扩展所提供的任何额外值。
* 客户端不识别的任何 `resultType` 值 **MUST** 被视为无效。
* 为了与实现早期协议版本的服务器保持向后兼容（这些版本不包含 `resultType`），客户端 **MUST** 将缺失的 `resultType` 视为 `"complete"`。

#### 错误响应

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

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

* 错误响应 **MUST** 包含与其对应请求相同的 ID（由于请求格式错误而无法读取 ID 的错误情况除外）。
* 错误响应 **MUST** 包含带有 `code` 和 `message` 的 `error` 字段。
* 错误码 **MUST** 是整数。

### 通知

[通知](/specification/draft/schema#jsonrpcnotification)作为单向消息从客户端发送到服务器，或反向发送。
接收方 **MUST NOT** 发送响应。

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

* 通知 **MUST NOT** 包含 ID。

### 消息模式

Model Context Protocol (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)**：客户端订阅来自服务器的通知流，通知会在事件发生时发送。

## 无状态性

Model Context Protocol (MCP) 是一个**无状态协议**：处理请求所需的所有信息都包含在请求本身中。
服务器独立处理每个请求；不应从以前的请求推断任何状态，即使这些请求位于同一连接或同一流上。

具体而言：

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

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

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

<Info>
  如需了解按请求模型如何映射到 SDK 代码，请参见
  [架构指南](/docs/learn/architecture#example)。
</Info>

## 授权

MCP 提供了用于 HTTP 的[授权](/specification/draft/basic/authorization)框架。
使用基于 HTTP 的传输的实现 **SHOULD** 遵循此规范，而使用 STDIO 传输的实现
**SHOULD NOT** 遵循此规范，而应从环境中获取凭据。

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

如需进一步讨论并参与 MCP 授权机制的演进，请加入
[GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions)，
帮助塑造该协议的未来！

## Schema

协议的完整规范定义为
[TypeScript schema](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 Usage

Model Context Protocol 在整个协议中使用 JSON Schema 进行校验。本节阐明应如何在 MCP 消息中使用 JSON Schema。

### Schema 方言

MCP 根据以下规则支持 JSON Schema：

1. **默认方言**：当 schema 不包含 `$schema` 字段时，默认使用 [JSON Schema 2020-12](https://json-schema.org/draft/2020-12/schema)
2. **显式方言**：Schema MAY 包含 `$schema` 字段以指定不同方言
3. **支持的方言**：实现 MUST 至少支持 2020-12，并 SHOULD 记录其支持的其他方言
4. **建议**：实现者 **RECOMMENDED** 使用 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` 字段的 schema，客户端和服务器 **MUST** 支持 JSON Schema 2020-12
* 客户端和服务器 **MUST** 根据 schema 声明的方言或默认方言进行校验。它们 **MUST** 通过返回适当错误来优雅处理不受支持的方言，指明该方言不受支持。
* 客户端和服务器 **SHOULD** 记录其支持的 schema 方言

### Schema 校验

* Schema **MUST** 根据其声明的方言或默认方言有效

### `$ref` Resolution

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

实现 **MAY** 提供一种选择加入模式，用于获取非本地 `$ref`，但该模式默认 **MUST** 禁用，并且
**SHOULD** 强制使用主机允许列表；或者至少拒绝环回、链路本地和私有网络地址，
应用超时和大小限制，并记录被解引用的 URI。

由于未解析的外部 `$ref` 而无法校验的 schema **SHOULD** 被拒绝，而不是被静默视为宽松允许。

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

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

## 通用字段

### `_meta`

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

如下所述，某些键名由 MCP 保留用于协议层元数据；实现 MUST NOT 对这些键上的值作出假设。

此外，[schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/draft/schema.ts)
中的定义可能会为特定用途的元数据保留特定名称，具体以这些定义中的声明为准。

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

**前缀：**

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

**名称：**

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

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

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

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

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

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

对于通过 [`subscriptions/listen`][subscriptions-listen] 流交付的通知，服务器 **MUST** 在 `_meta` 中包含
`io.modelcontextprotocol/subscriptionId`，以便客户端将通知与发起订阅请求相关联。

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

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

**OpenTelemetry trace context：**

作为上述前缀要求的例外，键 `traceparent`、`tracestate` 和 `baggage` 保留用于
[OpenTelemetry](https://opentelemetry.io/) trace context 传播。出现时，它们的值 MUST 分别遵循
[W3C Trace Context](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` 中 trace context 的非规范性示例：

```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"]`、用于 SVG 等可缩放格式的 `["any"]`，或用于多个尺寸的 `["48x48", "96x96"]`）
* `theme`：图标背景的可选主题偏好（`light` 或 `dark`）

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

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

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

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

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

**安全考量：**

图标元数据的消费者在处理图标时 **MUST** 采取适当安全预防措施，以防止被攻陷：

* 将图标元数据和图标字节视为不可信输入，并防御网络、隐私和解析风险。
* 确保图标 URI 是 HTTPS 或 `data:` URI。客户端 **MUST** 拒绝使用不安全方案和重定向的图标 URI，例如 `javascript:`、`file:`、`ftp:`、`ws:` 或本地应用 URI 方案。
  * 禁止方案变更以及重定向到不同来源的主机。
* 能够抵御由超大图像、大尺寸或过多帧（例如 GIF 中的帧）导致的资源耗尽攻击。
  * 消费者 **MAY** 设置图像和内容大小限制。
* 获取图标时不携带凭据。不要发送 Cookie、`Authorization` 头或客户端凭据。
* 校验图标 URI 与服务器同源。这可以最大限度降低向第三方暴露数据或跟踪信息的风险。
* 获取和渲染图标时要谨慎，因为载荷 **MAY** 包含可执行内容（例如带有[嵌入式 JavaScript](https://www.w3.org/TR/SVG11/script.html) 或[扩展能力](https://www.w3.org/TR/SVG11/extend.html)的 SVG）。
  * 消费者 **MAY** 选择禁止特定文件类型，或在渲染前以其他方式清理图标文件。
* 在渲染前校验 MIME 类型和文件内容。将 MIME 类型信息视为提示。通过魔数检测内容类型；在不匹配或类型未知时拒绝。
  * 维护严格的图像类型允许列表。

**用法：**

图标可以附加到：

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

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