> ## 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.
# 概览
Model Context Protocol 由多个相互协作的关键组件组成：
* **基础协议**：核心 JSON-RPC 消息类型
* **生命周期管理**：连接初始化、能力协商和会话控制
* **授权**：面向基于 HTTP 的传输的身份认证与授权框架
* **服务器功能**：服务器公开的资源、提示和工具
* **客户端功能**：客户端提供的采样和根目录列表
* **实用机制**：日志记录和参数补全等横切关注点
所有实现 **MUST** 支持基础协议和生命周期管理组件。其他组件 **MAY** 根据应用的具体需求实现。
这些协议层在支持客户端和服务器之间丰富交互的同时，建立了清晰的关注点分离。模块化设计允许实现只支持自身需要的功能。
## 消息
MCP 客户端和服务器之间的所有消息 **MUST** 遵循 [JSON-RPC 2.0](https://www.jsonrpc.org/specification) 规范。协议定义了以下消息类型：
### 请求
[请求](/specification/2025-11-25/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。
### 响应
响应用于回复请求，其中包含操作结果或错误。
#### 结果响应
[结果响应](/specification/2025-11-25/schema#jsonrpcresultresponse)在操作成功完成时发送。
```typescript theme={null}
{
jsonrpc: "2.0";
id: string | number;
result: {
[key: string]: unknown;
}
}
```
* 结果响应 **MUST** 包含与其对应请求相同的 ID。
* 结果响应 **MUST** 包含 `result` 字段。
* `result` **MAY** 遵循任意 JSON 对象结构。
#### 错误响应
[错误响应](/specification/2025-11-25/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/2025-11-25/schema#jsonrpcnotification)作为单向消息由客户端发送给服务器，或由服务器发送给客户端。接收方 **MUST NOT** 发送响应。
```typescript theme={null}
{
jsonrpc: "2.0";
method: string;
params?: {
[key: string]: unknown;
};
}
```
* 通知 **MUST NOT** 包含 ID。
## 授权
MCP 提供了用于 HTTP 的[授权](/specification/2025-11-25/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/2025-11-25/schema.ts)。这是所有协议消息和结构的事实来源。
此外还有一个 [JSON Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-11-25/schema.json)，它从作为事实来源的 TypeScript 自动生成，供各种自动化工具使用。
## JSON Schema 用法
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. **建议**：实现者使用 JSON Schema 2020-12 是 **RECOMMENDED** 的。
### 示例用法
#### 默认方言 (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** 按其声明方言或默认方言保持有效
## 通用字段
### `_meta`
`_meta` 属性/参数由 MCP 保留，用于允许客户端和服务器为其交互附加额外元数据。
如下所述，某些键名由 MCP 保留用于协议级元数据；实现 **MUST NOT** 对这些键处的值作出假设。
此外，[schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-11-25/schema.ts) 中的定义可能会按定义中的声明，为特定用途的元数据保留特定名称。
**键名格式：** 有效的 `_meta` 键名包含两个部分：可选的 **prefix** 和 **name**。
**Prefix：**
* 如果指定，**MUST** 是一系列以点号 (`.`) 分隔的标签，后跟一个斜杠 (`/`)。
* 标签 **MUST** 以字母开头，并以字母或数字结尾；中间字符可以是字母、数字或连字符 (`-`)。
* 实现 **SHOULD** 使用反向 DNS 表示法（例如 `com.example/`，而不是 `example.com/`）。
* 第二个标签为 `modelcontextprotocol` 或 `mcp` 的任何 prefix 都为 MCP 使用而**保留**。
* 例如：`io.modelcontextprotocol/`、`dev.mcp/`、`org.modelcontextprotocol.api/` 和 `com.mcp.tools/` 均为保留。
* 但是，`com.example.mcp/` 不保留，因为第二个标签是 `example`。
**Name：**
* 除非为空，否则 **MUST** 以字母数字字符 (`[a-z0-9A-Z]`) 开头和结尾。
* 中间 **MAY** 包含连字符 (`-`)、下划线 (`_`)、点号 (`.`) 和字母数字字符。
### `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** 拒绝使用不安全 scheme 和重定向的图标 URI，例如 `javascript:`、`file:`、`ftp:`、`ws:` 或本地应用 URI scheme。
* 禁止 scheme 变更以及重定向到不同 origin 的主机。
* 能够抵御由超大图片、大尺寸或过多帧（例如 GIF 中）导致的资源耗尽攻击。
* 使用方 **MAY** 设置图片和内容大小限制。
* 获取图标时不带凭据。不要发送 cookies、`Authorization` header 或客户端凭据。
* 验证图标 URI 与服务器同源。这可以最大限度降低向第三方暴露数据或跟踪信息的风险。
* 获取和渲染图标时应谨慎，因为 payload **MAY** 包含可执行内容（例如带有[嵌入式 JavaScript](https://www.w3.org/TR/SVG11/script.html) 或[扩展能力](https://www.w3.org/TR/SVG11/extend.html)的 SVG）。
* 使用方 **MAY** 选择禁止特定文件类型，或在渲染前以其他方式清理图标文件。
* 渲染前验证 MIME 类型和文件内容。将 MIME 类型信息视为建议性信息。通过 magic bytes 检测内容类型；若不匹配或类型未知则拒绝。
* 维护严格的图片类型 allowlist。
**用法：**
图标可以附加到：
* `Implementation`：MCP 服务器/客户端实现的视觉标识符
* `Tool`：工具功能的视觉表示
* `Prompt`：与提示模板一起显示的图标
* `Resource`：不同资源类型的视觉指示
可以提供多个图标来支持不同显示上下文和分辨率。客户端应根据其 UI 需求选择最合适的图标。