概述

模型上下文协议由以下几个协同工作的关键组件组成：

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

所有实现都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: {
    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 对象，说明所需的附加信息。
• 扩展MAY增加其他 ResultType 值。支持的 ResultType 值集合MUST由核心协议定义的集合，以及通过 capabilities 通告的受支持扩展所增加的值共同构成。
• 客户端无法识别的任何 resultType 值都MUST视为无效。
• 为了向后兼容未包含 resultType 的早期协议版本服务器，客户端MUST将缺失的 resultType 视为 "complete"。

错误响应

操作失败或遇到错误时发送错误响应（英文） 。

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

• 错误响应MUST包含与对应请求相同的 ID（因请求格式错误而无法读取 ID 的错误情况除外）。
• 错误响应MUST包含带有 code 和 message 的 error 字段。
• 错误码MUST是整数。
• 错误响应MAY包含任意类型的 data 成员，用于提供附加信息，例如嵌套错误。

错误码

MCP 使用标准 JSON-RPC 2.0 错误码（-32700、-32600 至 -32603）表示一般协议故障。

JSON-RPC 2.0 将 -32000 至 -32099 保留为实现自定义的服务器错误。MCP 对该范围作如下划分：

• -32000 至 -32019 — 旧版。 该子范围内的错误码是在本策略引入前由实现分配的。新错误码MUST NOT分配到该子范围，新实现也SHOULD NOT使用该子范围中的任何错误码。除 -32002（见下文）外，接收方MUST NOT假定这些错误码具有任何特定含义。
• -32020 至 -32099 — 为 MCP 规范保留。 该子范围内的错误码仅由 MCP 规范定义，并记录在 schema（英文） 中。实现MUST NOT发送本规范未定义的该子范围错误码，并且对已定义错误码也MUST仅按其规定含义使用。

MCP 定义以下错误码：

早期协议版本定义的错误码仍然保留，不会复用。本协议版本的实现MUST NOT发送这些错误码：

• -32002 — 找不到资源（2025-11-25 及更早版本；已由 -32602 取代）。客户端从实现早期版本的服务器收到该错误码时，SHOULD仍然接受 -32002（英文） 。
• -32042 — 需要 URL 信息征询（仅 2025-11-25）。

纯粹由实现本地生成的错误（例如 SDK 内部抛出的请求超时）目前没有由本规范分配错误码。以类似 JSON-RPC 的结构公开本地错误时，实现应确保这些错误不会被误认为是从对端收到的错误。未来版本的规范可能会在保留子范围中为常见本地错误定义标准错误码。

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

通知

通知（英文） 由客户端发送给服务器或由服务器发送给客户端，是一种单向消息。接收方MUST NOT发送响应。

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

• 通知MUST NOT包含 ID。

消息模式

模型上下文协议（MCP）支持多种消息模式 ，用于定义客户端与服务器的交互方式：

1. 请求与响应 ：客户端向服务器发送请求，服务器以结果或错误作答。
2. 多轮往返请求（MRTR） ：服务器需要额外的客户端输入（采样（Sampling）、信息征询（Elicitation）或根目录（Roots））才能完成请求。
3. 订阅与通知 ：客户端订阅来自服务器的通知流，服务器在事件发生时发送通知。

无状态性

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

具体而言：

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

像 subscriptions/listen 这样的长期请求仍属于请求/响应；只不过其响应是一条打开的通知流。相关状态限定于请求自身，而不是底层连接。

身份验证

MCP 提供用于 HTTP 的授权框架（英文） 。使用基于 HTTP 的传输时，实现SHOULD遵循本规范；使用 STDIO 传输时，实现SHOULD NOT遵循本规范，而应从环境中获取凭据。

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

如需进一步讨论 MCP 身份验证机制的演进并参与贡献，请加入 GitHub Discussions ，共同塑造协议的未来。

Schema

协议的完整规范由 TypeScript schema 定义。它是所有协议消息和结构的真相源。

此外还有一个 JSON Schema ，该文件从作为真相源的 TypeScript 自动生成，可供各种自动化工具使用。

JSON Schema 用法

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

Schema 方言

MCP 按以下规则支持 JSON Schema：

1. 默认方言：schema 不包含 $schema 字段时，默认使用 JSON Schema 2020-12
2. 显式方言：schema MAY包含 $schema 字段，以指定其他方言
3. 支持的方言：实现MUST至少支持 2020-12，并SHOULD记录其支持的其他方言
4. 建议：实现者使用 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符合其声明或默认方言并保持有效

$ref 解析

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

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

如果 schema 因外部 $ref 无法解析而验证失败，则SHOULD拒绝该 schema，而不是静默地将其视为宽松 schema。

组合关键字的资源使用

组合关键字（anyOf、oneOf、allOf、if/then/else）和 $defs 能表达复杂 schema，但验证成本可能很高。实现SHOULD设置合理边界，例如最大 schema 深度、子 schema 总数上限或单次验证时间预算，防止恶意 schema 对验证器造成拒绝服务攻击。

通用字段

_meta

MCP 使用 _meta 属性/参数，使客户端和服务器能够为其交互附加额外元数据。

MCP 为协议级元数据保留了下述特定键名；实现MUST NOT对这些键的值作出假设。

键名格式：有效的 _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包含连字符（-）、下划线（_）、点（.）和字母数字字符。

保留键：

本规范保留以下 _meta 键：

官方扩展 在 io.modelcontextprotocol/ 前缀下定义其他 _meta 键，第三方扩展则使用自己的供应商前缀。两种情况下，这些键都在对应扩展文档中定义。

逐请求协议字段：

客户端请求在 _meta 中携带以下 io.modelcontextprotocol/* 字段；标记为必需的字段MUST包含在每个请求中。服务器使用这些字段识别正在使用的协议版本和能力，而不依赖任何先前连接状态。版本协商规则参见版本与兼容性 。

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

除非明确配置为不发送，否则客户端SHOULD在每个请求中包含 io.modelcontextprotocol/clientInfo。

服务器MUST NOT依赖客户端未声明的能力。如果处理请求需要客户端未包含在 io.modelcontextprotocol/clientCapabilities 中的能力，服务器MUST返回 MissingRequiredClientCapabilityError（英文） （-32021），其 data.requiredCapabilities 列出缺失的能力。在 HTTP 上，响应状态MUST为 400 Bad Request。

逐响应协议字段：

除非明确配置为不发送，否则服务器SHOULD在每个结果的 _meta 中包含以下 io.modelcontextprotocol/* 字段，以在不依赖任何先前连接状态的情况下标识自身：

对于通过 subscriptions/listen 流传送的通知，服务器MUST在 _meta 中包含 io.modelcontextprotocol/subscriptionId，以便客户端将通知与其来源订阅请求相关联。

OpenTelemetry 追踪上下文：

作为上述前缀要求的例外，traceparent、tracestate 和 baggage 键保留用于 OpenTelemetry 追踪上下文传播。存在这些键时，其值MUST分别遵循 W3C Trace Context 和 W3C Baggage 格式。

该例外用于保持与现有实现以及 MCP 的 OpenTelemetry 语义约定 兼容。

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

{
  "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 编码图像数据的数据 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:。客户端MUST拒绝使用不安全 scheme 和重定向的图标 URI，例如 javascript:、file:、ftp:、ws: 或本地应用 URI scheme。
  • 禁止 scheme 发生变化，也禁止重定向到不同源的主机。
• 应能抵御超大图像、过大尺寸或过多帧（例如 GIF）造成的资源耗尽攻击。
  • 使用方MAY设置图像和内容大小限制。
• 获取图标时不得携带凭据。不要发送 Cookie、Authorization Header 或客户端凭据。
• 验证图标 URI 与服务器同源，以尽量减少向第三方泄露数据或跟踪信息的风险。
• 获取和渲染图标时应保持谨慎，因为有效载荷MAY包含可执行内容，例如带有嵌入式 JavaScript 或扩展能力 的 SVG。
  • 使用方MAY选择禁止特定文件类型，或在渲染前对图标文件进行清理。
• 渲染前验证 MIME 类型和文件内容。将 MIME 类型信息视为提示；通过魔数检测内容类型，不匹配或类型未知时拒绝。
  • 维护严格的图像类型允许列表。

用法：

图标可以附加到：

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

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