概览 - Model Context Protocol 中文文档

Model Context Protocol 由多个相互协作的关键组件组成：

基础协议：核心 JSON-RPC 消息类型
生命周期管理：连接初始化、能力协商和会话控制
授权：面向基于 HTTP 的传输的身份认证与授权框架
服务器功能：服务器公开的资源、提示和工具
客户端功能：客户端提供的采样和根目录列表
实用机制：日志记录和参数补全等横切关注点

所有实现 MUST 支持基础协议和生命周期管理组件。其他组件 MAY 根据应用的具体需求实现。这些协议层在支持客户端和服务器之间丰富交互的同时，建立了清晰的关注点分离。模块化设计允许实现只支持自身需要的功能。

消息

MCP 客户端和服务器之间的所有消息 MUST 遵循 JSON-RPC 2.0 规范。协议定义了以下消息类型：

请求

请求由客户端发送给服务器，或由服务器发送给客户端，用于发起一项操作。

{
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params?: {
    [key: string]: unknown;
  };
}

请求 MUST 包含字符串或整数 ID。
与基础 JSON-RPC 不同，ID MUST NOT 为 null。
请求 ID MUST NOT 是请求方在同一会话中先前使用过的 ID。

响应

响应用于回复请求，其中包含操作结果或错误。

结果响应

结果响应在操作成功完成时发送。

{
  jsonrpc: "2.0";
  id: string | number;
  result: {
    [key: string]: unknown;
  }
}

结果响应 MUST 包含与其对应请求相同的 ID。
结果响应 MUST 包含 result 字段。
result MAY 遵循任意 JSON 对象结构。

错误响应

错误响应在操作失败或遇到错误时发送。

{
  jsonrpc: "2.0";
  id?: string | number;
  error: {
    code: number;
    message: string;
    data?: unknown;
  }
}

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

通知

通知作为单向消息由客户端发送给服务器，或由服务器发送给客户端。接收方 MUST NOT 发送响应。

{
  jsonrpc: "2.0";
  method: string;
  params?: {
    [key: string]: unknown;
  };
}

通知 MUST NOT 包含 ID。

授权

MCP 提供了用于 HTTP 的授权框架。使用基于 HTTP 的传输的实现 SHOULD 遵循本规范，而使用 STDIO 传输的实现 SHOULD NOT 遵循本规范，应改为从环境中检索凭据。此外，客户端和服务器 MAY 协商自己的自定义身份认证和授权策略。如需进一步讨论并参与 MCP 授权机制的演进，请加入 GitHub Discussions，共同塑造协议的未来。

Schema

协议的完整规范定义为 TypeScript schema。这是所有协议消息和结构的事实来源。此外还有一个 JSON Schema，它从作为事实来源的 TypeScript 自动生成，供各种自动化工具使用。

JSON Schema 用法

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

Schema 方言

MCP 按以下规则支持 JSON Schema：

默认方言：当 schema 不包含 $schema 字段时，默认使用 JSON Schema 2020-12
显式方言：Schema MAY 包含 $schema 字段来指定不同方言
支持的方言：实现 MUST 至少支持 2020-12，并且 SHOULD 记录其支持的其他方言
建议：实现者使用 JSON Schema 2020-12 是 RECOMMENDED 的。

示例用法

默认方言 (2020-12)：

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

显式方言 (draft-07)：

{
  "$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 中的定义可能会按定义中的声明，为特定用途的元数据保留特定名称。 键名格式： 有效的 _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 或扩展能力的 SVG）。
- 使用方 MAY 选择禁止特定文件类型，或在渲染前以其他方式清理图标文件。
渲染前验证 MIME 类型和文件内容。将 MIME 类型信息视为建议性信息。通过 magic bytes 检测内容类型；若不匹配或类型未知则拒绝。
- 维护严格的图片类型 allowlist。

用法： 图标可以附加到：

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

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

基础协议

客户端能力

服务器能力

概览

消息

请求

响应

结果响应

错误响应

通知

授权

Schema

JSON Schema 用法

Schema 方言

示例用法

默认方言 (2020-12)：

显式方言 (draft-07)：

实现要求

Schema 验证

通用字段

`_meta`

`icons`

​消息

​请求

​响应

​结果响应

​错误响应

​通知

​授权

​Schema

​JSON Schema 用法

​Schema 方言

​示例用法

​默认方言 (2020-12)：

​显式方言 (draft-07)：

​实现要求

​Schema 验证

​通用字段

​_meta

​icons

消息

请求

响应

结果响应

错误响应

通知

授权

Schema

JSON Schema 用法

Schema 方言

示例用法

默认方言 (2020-12)：

显式方言 (draft-07)：

实现要求

Schema 验证

通用字段

`_meta`

`icons`