鸭梨公共文档

主题

概述 ​

协议修订版本：2025-11-25

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

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

所有实现必须支持基础协议和生命周期管理组件。其他组件可以根据应用程序的具体需求进行实现。

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

1. 消息 ​

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

1.1 请求 ​

请求从客户端发送到服务器或反之，以启动操作。

typescript
{
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params?: {
    [key: string]: unknown;
  };
}
  • 请求必须包含字符串或整数 ID。
  • 与基础 JSON-RPC 不同，ID 不得为 null。
  • 请求 ID 不得在同一会话中被请求者先前使用过。

1.2 响应 ​

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

1.2.1 结果响应 ​

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

typescript
{
  jsonrpc: "2.0";
  id: string | number;
  result: {
    [key: string]: unknown;
  }
}
  • 结果响应必须包含与其对应请求相同的 ID。
  • 结果响应必须包含 result 字段。
  • result 可以遵循任何 JSON 对象结构。

1.2.2 错误响应 ​

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

typescript
{
  jsonrpc: "2.0";
  id?: string | number;
  error: {
    code: number;
    message: string;
    data?: unknown;
  }
}
  • 错误响应必须包含与其对应请求相同的 ID（除了由于格式错误的请求导致无法读取 ID 的错误情况）。
  • 错误响应必须包含带有 code 和 message 的 error 字段。
  • 错误代码必须是整数。

1.3 通知 ​

通知从客户端发送到服务器或反之，作为单向消息。接收者不得发送响应。

typescript
{
  jsonrpc: "2.0";
  method: string;
  params?: {
    [key: string]: unknown;
  };
}
  • 通知不得包含 ID。

2. 授权 ​

MCP 为 HTTP 使用提供了授权框架。使用基于 HTTP 传输的实现应该符合此规范，而使用 STDIO 传输的实现不应该遵循此规范，而应该从环境中检索凭据。

此外，客户端和服务器可以协商自己的自定义身份验证和授权策略。

关于 MCP 认证机制演进的进一步讨论和贡献，请加入我们在 GitHub Discussions 的讨论，帮助塑造协议的未来！

3. 模式 ​

协议的完整规范定义为 TypeScript 模式。这是所有协议消息和结构的权威来源。

还有一个 JSON Schema，它是从 TypeScript 权威来源自动生成的，用于各种自动化工具。

4. JSON Schema 使用 ​

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

4.1 模式方言 ​

MCP 支持 JSON Schema，遵循以下规则：

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

4.2 示例用法 ​

4.2.1 默认方言 (2020-12) ​

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

4.2.2 显式方言 (draft-07) ​

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

4.3 实现要求 ​

  • 客户端和服务器必须为没有显式 $schema 字段的模式支持 JSON Schema 2020-12
  • 客户端和服务器必须根据声明的或默认的方言验证模式。它们必须通过返回指示不支持该方言的适当错误来优雅地处理不支持的方言。
  • 客户端和服务器应该记录它们支持的模式方言

4.4 模式验证 ​

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

5. 通用字段 ​

5.1 _meta ​

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

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

此外，模式中的定义可能为特定目的的元数据保留特定名称，如这些定义中所声明的。

键名格式： 有效的 _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]）开头和结尾。
  • 可以在中间包含连字符（-）、下划线（_）、点（.）和字母数字字符。

5.2 icons ​

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

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

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

必需的 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 中）的资源耗尽攻击保持弹性。
    • 消费者可以为图像和内容大小设置限制。
  • 获取图标时不带凭据。不要发送 cookies、Authorization 头或客户端凭据。
  • 验证图标 URI 来自与服务器相同的来源。这最大限度地降低了向第三方暴露数据或跟踪信息的风险。
  • 获取和渲染图标时要谨慎，因为负载可能包含可执行内容（例如，带有嵌入式 JavaScript 或扩展功能的 SVG）。
    • 消费者可以选择禁止特定文件类型或在渲染前对图标文件进行清理。
  • 在渲染前验证 MIME 类型和文件内容。将 MIME 类型信息视为建议性的。通过魔数字节检测内容类型；在不匹配或未知类型时拒绝。
    • 维护严格的图像类型白名单。

用法：

图标可以附加到：

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

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