概述 - MCP 中文文档

模型上下文协议由几个关键组件组成，它们协同工作：

基础协议：核心 JSON-RPC 消息类型
生命周期管理：协议版本协商和按请求能力声明
授权：基于 HTTP 传输的认证和授权框架
服务器功能：由服务器公开的资源、提示和工具
客户端功能：由客户端提供的采样和根目录列表
实用工具：日志记录和参数补全等横切关注点

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

消息

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

请求

请求由客户端发送给服务器，反之亦然，以启动操作。

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

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

响应

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

结果响应

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

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

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

ResultType

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

resultType 为 "complete" 表示请求已成功完成，结果包含最终内容。
resultType 为 "input_required" 表示请求尚未完成，处理请求还需要更多信息。结果包含一个 InputRequiredResult 对象，其中包含所需的附加信息。
为了向后兼容较早协议版本的服务器（这些版本不包含 resultType），客户端必须将缺失的 resultType 视为 "complete"。

错误响应

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

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

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

通知

通知由客户端发送给服务器，反之亦然，作为单向消息。接收者不得发送响应。

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

通知不得包含 ID。

授权

MCP 提供了一个用于 HTTP 的授权框架。使用基于 HTTP 传输的实现应该符合此规范，而使用 STDIO 传输的实现 不应该 遵循此规范，而是从环境中检索凭据。此外，客户端和服务器可以协商它们自己的自定义认证和授权策略。如需进一步讨论并为 MCP 认证机制的发展做出贡献，请加入 GitHub 讨论区来帮助塑造协议的未来！

模式

协议的完整规范定义为 TypeScript 模式。这是所有协议消息和结构的真实来源。还有一个 JSON Schema，它是从 TypeScript 真实来源自动生成的，用于各种自动化工具。

JSON Schema 用法

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

模式方言

MCP 支持带有以下规则的 JSON Schema：

默认方言：当模式不包含 $schema 字段时，默认为 JSON Schema 2020-12
显式方言：模式可以包含 $schema 字段以指定不同的方言
支持的方言：实现必须至少支持 2020-12 并应该记录它们支持哪些其他方言
建议：建议实现者使用 JSON Schema 2020-12。

用法示例

默认方言 (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 字段的模式的 JSON Schema 2020-12
客户端和服务器必须根据其声明的或默认的方言验证模式。他们必须优雅地处理不支持的方言，返回适当的错误表明该方言不受支持。
客户端和服务器应该记录它们支持哪些模式方言

模式验证

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

通用字段

`_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]) 开头和结尾。
中间可以包含连字符 (-)、下划线 (_)、点 (.) 和字母数字字符。

每请求协议字段： 每个客户端请求必须在 _meta 中包含以下 io.modelcontextprotocol/* 字段。服务器使用这些字段来识别客户端和正在使用的协议版本，而无需依赖任何先前的连接状态。有关版本协商规则，请参见生命周期。

Key	Type	Required	Description
`io.modelcontextprotocol/protocolVersion`	`string`	Yes	此请求的协议版本（例如 `"DRAFT-2026-v1"`）
`io.modelcontextprotocol/clientInfo`	`Implementation`	Yes	客户端名称和版本
`io.modelcontextprotocol/clientCapabilities`	`ClientCapabilities`	Yes	与此请求相关的客户端能力
`io.modelcontextprotocol/logLevel`	`LoggingLevel`	No	服务器应为此请求输出的最低日志级别

服务器不得依赖客户端未声明的能力。如果处理请求需要客户端未在 io.modelcontextprotocol/clientCapabilities 中包含的能力，服务器必须返回 MissingRequiredClientCapabilityError （-32003），其 data.requiredCapabilities 列出缺失的能力。在 HTTP 上，响应状态必须为 400 Bad Request。对于通过 subscriptions/listen 流传递的通知，服务器必须在 _meta 中包含 io.modelcontextprotocol/subscriptionId，以便客户端可以将通知与源订阅请求关联起来。 OpenTelemetry 追踪上下文： 作为对上述前缀要求的例外，键 traceparent、tracestate 和 baggage 保留用于 OpenTelemetry 追踪上下文传播。当存在时，它们的值必须分别遵循 W3C 追踪上下文和 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 编码图像数据的 data URI
mimeType：如果服务器的类型缺失或通用，则为可选的 MIME 类型
sizes：可选的尺寸规格数组（例如，["48x48"]、["any"] 用于 SVG 等可缩放格式，或 ["48x48", "96x96"] 用于多种尺寸）
theme：图标背景的可选主题偏好（light 或 dark）

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

用法： 图标可以附加到：

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

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

Documentation Index

​消息

​请求

​响应

​结果响应

ResultType

​错误响应

​通知

​授权

​模式

​JSON Schema 用法

​模式方言

​用法示例

​默认方言 (2020-12):

​显式方言 (draft-07):

​实现要求

​模式验证

​通用字段

​_meta

​icons

消息

请求

响应