1.🎯 概述 #

Model Context Protocol (MCP) 架构参考文档提供了完整的协议规范，包括所有数据类型、接口定义和消息格式。本文档是开发MCP服务器和客户端的权威参考。

2. 文档结构 #

本文档按以下结构组织：

1. 常见类型 - 基础数据类型和接口
2. 消息类型 - 协议消息的格式和结构
3. 错误代码 - 标准错误代码和含义
4. 工具定义 - 工具相关的数据结构
5. 资源定义 - 资源相关的数据结构
6. 采样定义 - 采样相关的数据结构

3.🔧 常见类型 #

3.1 Annotations（注解） #

客户端的可选注解。客户端可以利用注解来指示对象的使用或显示方式。

interface Annotations {
  audience?: Role[];           // 目标受众
  lastModified?: string;       // 最后修改时间
  priority?: number;           // 优先级
}

属性说明 #

属性	类型	必需	描述
audience	Role[]	否	描述此对象或数据的目标客户是谁。可以包含多个条目，表明内容对多个受众群体都有用（例如，["user", "assistant"]）
lastModified	string	否	资源最后修改的时刻，以ISO 8601格式字符串表示。应为ISO 8601格式的字符串（例如"2025-01-12T15:00:58Z"）
priority	number	否	描述这些数据对服务器运行的重要性。值为1表示"最重要"，值为0表示"最不重要"

3.2 AudioContent（音频内容） #

提供给或来自LLM的音频。

interface AudioContent {
  _meta?: { [key: string]: unknown };  // 元数据
  annotations?: Annotations;            // 注解
  data: string;                        // 数据
  mimeType: string;                    // MIME类型
  type: "audio";                       // 类型
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段，请参阅规范了解使用说明
annotations	Annotations	否	客户端的可选注解
data	string	是	base64编码的音频数据
mimeType	string	是	音频的MIME类型。不同提供商可能支持不同的音频格式
type	"audio"	是	固定值"audio"

3.3 BlobResourceContents（二进制资源内容） #

特定资源或子资源的内容。

interface BlobResourceContents {
  _meta?: { [key: string]: unknown };  // 元数据
  blob: string;                         // 二进制数据
  mimeType?: string;                    // MIME类型
  uri: string;                          // URI
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段，请参阅规范了解使用说明
blob	string	是	表示项目二进制数据的base64编码字符串
mimeType	string	否	此资源的MIME类型（如果已知）
uri	string	是	资源的统一资源标识符

3.4 BinaryContent（二进制内容） #

提供给或来自LLM的二进制数据。

interface BinaryContent {
  _meta?: { [key: string]: unknown };  // 元数据
  annotations?: Annotations;            // 注解
  data: string;                         // 数据
  mimeType: string;                     // MIME类型
  type: "binary";                       // 类型
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段
annotations	Annotations	否	客户端的可选注解
data	string	是	base64编码的二进制数据
mimeType	string	是	数据的MIME类型
type	"binary"	是	固定值"binary"

3.5 Capabilities（能力） #

服务器支持的功能。

interface Capabilities {
  sampling?: {};                        // 采样能力
  resources?: {};                       // 资源能力
  tools?: {};                          // 工具能力
  prompts?: {};                        // 提示能力
  completions?: {};                    // 完成能力
  logging?: {};                        // 日志能力
  pagination?: {};                     // 分页能力
}

属性说明 #

属性	类型	必需	描述
sampling	{}	否	支持采样功能
resources	{}	否	支持资源功能
tools	{}	否	支持工具功能
prompts	{}	否	支持提示功能
completions	{}	否	支持完成功能
logging	{}	否	支持日志功能
pagination	{}	否	支持分页功能

3.6 CompletionResult（完成结果） #

自动完成的结果。

interface CompletionResult {
  _meta?: { [key: string]: unknown };  // 元数据
  annotations?: Annotations;            // 注解
  content: string;                      // 内容
  type: "completion";                   // 类型
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段
annotations	Annotations	否	客户端的可选注解
content	string	是	完成的内容
type	"completion"	是	固定值"completion"

3.7 CompletionResultList（完成结果列表） #

自动完成结果的列表。

interface CompletionResultList {
  _meta?: { [key: string]: unknown };  // 元数据
  annotations?: Annotations;            // 注解
  results: CompletionResult[];          // 结果列表
  type: "completion-list";              // 类型
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段
annotations	Annotations	否	客户端的可选注解
results	CompletionResult[]	是	完成结果列表
type	"completion-list"	是	固定值"completion-list"

3.8 DataSource（数据源） #

数据源的描述。

interface DataSource {
  _meta?: { [key: string]: unknown };  // 元数据
  annotations?: Annotations;            // 注解
  name: string;                         // 名称
  description: string;                  // 描述
  uri: string;                          // URI
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段
annotations	Annotations	否	客户端的可选注解
name	string	是	数据源的名称
description	string	是	数据源的描述
uri	string	是	数据源的URI

3.9 Embedding（嵌入） #

文本嵌入的表示。

interface Embedding {
  _meta?: { [key: string]: unknown };  // 元数据
  annotations?: Annotations;            // 注解
  data: number[];                       // 数据
  dimensions: number;                   // 维度
  model: string;                        // 模型
  object: "embedding";                  // 对象类型
  usage: EmbeddingUsage;                // 使用情况
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段
annotations	Annotations	否	客户端的可选注解
data	number[]	是	嵌入向量数据
dimensions	number	是	嵌入的维度
model	string	是	使用的模型名称
object	"embedding"	是	固定值"embedding"
usage	EmbeddingUsage	是	使用情况统计

3.10 EmbeddingUsage（嵌入使用情况） #

嵌入操作的使用情况统计。

interface EmbeddingUsage {
  promptTokens: number;                 // 提示Access Token数
  totalTokens: number;                  // 总Access Token数
}

属性说明 #

属性	类型	必需	描述
promptTokens	number	是	提示中的Access Token数量
totalTokens	number	是	总Access Token数量

4.📝 更多基础类型 #

4.1 BooleanSchema（布尔模式） #

布尔值的JSON Schema定义。

interface BooleanSchema {
  default?: boolean;           // 默认值
  description?: string;        // 描述
  title?: string;             // 标题
  type: "boolean";            // 类型
}

属性说明 #

属性	类型	必需	描述
default	boolean	否	布尔值的默认值
description	string	否	字段的描述信息
title	string	否	字段的标题
type	"boolean"	是	固定值"boolean"

4.2 ClientCapabilities（客户端能力） #

客户端可能支持的功能。已知功能在此架构中定义，但这不是一个封闭的集合。

interface ClientCapabilities {
  elicitation?: object;                    // 引导能力
  experimental?: { [key: string]: object }; // 实验性功能
  roots?: { listChanged?: boolean };       // 根目录能力
  sampling?: object;                       // 采样能力
}

属性说明 #

属性	类型	必需	描述
elicitation	object	否	如果客户端支持从服务器端获取数据，则显示此项
experimental	{ [key: string]: object }	否	客户端支持的非标准实验性功能
roots	{ listChanged?: boolean }	否	展示客户端是否支持列出根目录。listChanged表示客户端是否支持对根列表变更的通知
sampling	object	否	如果客户端支持从LLM进行采样则呈现

4.3 ContentBlock（内容块） #

内容块的联合类型，可以是文本、图像、音频、资源链接或嵌入式资源。

type ContentBlock = 
  | TextContent
  | ImageContent
  | AudioContent
  | ResourceLink
  | EmbeddedResource;

4.4 Cursor（游标） #

用于表示分页游标的不透明Access Token。

type Cursor = string;

4.5 EmbeddedResource（嵌入式资源） #

资源的内容，嵌入到提示或工具调用结果中。客户端可自行决定如何最佳呈现嵌入式资源，以优化LLM和/或用户体验。

interface EmbeddedResource {
  _meta?: { [key: string]: unknown };     // 元数据
  annotations?: Annotations;               // 注解
  resource: TextResourceContents | BlobResourceContents; // 资源
  type: "resource";                        // 类型
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段，请参阅规范了解使用说明
annotations	Annotations	否	客户端的可选注解
resource	`TextResourceContents \	BlobResourceContents`	是	嵌入的资源内容
type	"resource"	是	固定值"resource"

4.6 EmptyResult（空结果） #

一个表示成功但不携带数据的响应。

type EmptyResult = Result;

4.7 EnumSchema（枚举模式） #

字符串枚举的JSON Schema定义。

interface EnumSchema {
  description?: string;        // 描述
  enum: string[];             // 枚举值
  enumNames?: string[];       // 枚举名称
  title?: string;             // 标题
  type: "string";             // 类型
}

属性说明 #

属性	类型	必需	描述
description	string	否	字段的描述信息
enum	string[]	是	允许的枚举值列表
enumNames	string[]	否	枚举值的显示名称
title	string	否	字段的标题
type	"string"	是	固定值"string"

4.8 ImageContent（图像内容） #

提供给或来自LLM的一张图像。

interface ImageContent {
  _meta?: { [key: string]: unknown };     // 元数据
  annotations?: Annotations;               // 注解
  data: string;                           // 数据
  mimeType: string;                       // MIME类型
  type: "image";                          // 类型
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段，请参阅规范了解使用说明
annotations	Annotations	否	客户端的可选注解
data	string	是	经过base64编码的图像数据
mimeType	string	是	图像的MIME类型。不同提供商可能支持不同的图像格式
type	"image"	是	固定值"image"

4.9 Implementation（实现） #

描述一个MCP实现的名称和版本，可选择性地包含用于UI显示的标题。

interface Implementation {
  name: string;               // 名称
  title?: string;             // 标题
  version: string;            // 版本
}

属性说明 #

属性	类型	必需	描述
name	string	是	本用于编程或逻辑用途，但在过去的规范中或作为后备方案（若标题不存在时）被用作显示名称
title	string	否	专为UI和终端用户场景设计——优化至人类可读且易于理解，即使不熟悉领域特定术语的用户也能轻松掌握。如果未提供，应使用名称进行显示
version	string	是	实现的版本号

4.10 JSONRPCError（JSON-RPC错误） #

表示请求处理过程中发生错误的响应。

interface JSONRPCError {
  error: {
    code: number;             // 错误代码
    data?: unknown;           // 错误数据
    message: string;          // 错误消息
  };
  id: RequestId;              // 请求ID
  jsonrpc: "2.0";            // JSON-RPC版本
}

属性说明 #

属性	类型	必需	描述
error.code	number	是	发生的错误类型
error.data	unknown	否	有关错误的附加信息。该成员的值由发送方定义（例如详细的错误信息、嵌套错误等）
error.message	string	是	错误的简短描述。消息应限制为简洁的单一句子
id	RequestId	是	对应请求的ID
jsonrpc	"2.0"	是	固定值"2.0"

5.📨 JSON-RPC 消息类型 #

5.1 JSONRPCNotification（JSON-RPC通知） #

不期待回应的通知。

interface JSONRPCNotification {
  jsonrpc: "2.0";                           // JSON-RPC版本
  method: string;                            // 方法名
  params?: {                                 // 参数
    _meta?: { [key: string]: unknown };      // 元数据
    [key: string]: unknown;                  // 其他参数
  };
}

属性说明 #

属性	类型	必需	描述
jsonrpc	"2.0"	是	固定值"2.0"
method	string	是	要调用的方法名
params	{ _meta?: { [key: string]: unknown }; [key: string]: unknown }	否	方法参数，包含可选的元数据字段

5.2 JSONRPCRequest（JSON-RPC请求） #

一个期望得到响应的请求。

interface JSONRPCRequest {
  id: RequestId;                             // 请求ID
  jsonrpc: "2.0";                           // JSON-RPC版本
  method: string;                            // 方法名
  params?: {                                 // 参数
    _meta?: {                                // 元数据
      progressToken?: ProgressToken;         // 进度Access Token
      [key: string]: unknown;                // 其他元数据
    };
    [key: string]: unknown;                  // 其他参数
  };
}

属性说明 #

属性	类型	必需	描述
id	RequestId	是	请求的唯一标识符
jsonrpc	"2.0"	是	固定值"2.0"
method	string	是	要调用的方法名
params._meta.progressToken	ProgressToken	否	如果指定此参数，调用方将请求为此操作获取带外进度通知。该参数的值是一个不透明的Access Token，将附加到所有后续通知中
params	{ _meta?: { progressToken?: ProgressToken; [key: string]: unknown }; [key: string]: unknown }	否	方法参数

5.3 JSONRPCResponse（JSON-RPC响应） #

请求的成功（无错误）响应。

interface JSONRPCResponse {
  id: RequestId;                             // 请求ID
  jsonrpc: "2.0";                           // JSON-RPC版本
  result: Result;                            // 结果
}

属性说明 #

属性	类型	必需	描述
id	RequestId	是	对应请求的ID
jsonrpc	"2.0"	是	固定值"2.0"
result	Result	是	请求的结果

6.🔧 日志和模型相关类型 #

6.1 LoggingLevel（日志级别） #

日志消息的严重程度。这些对应于RFC-5424中规定的syslog消息严重性等级。

type LoggingLevel = 
  | "debug"      // 调试
  | "info"       // 信息
  | "notice"     // 通知
  | "warning"    // 警告
  | "error"      // 错误
  | "critical"   // 关键
  | "alert"      // 警报
  | "emergency"; // 紧急

6.2 ModelHint（模型提示） #

模型选择的提示。此处未声明的键目前规范中未作明确规定，由客户端自行解释。

interface ModelHint {
  name?: string;                              // 模型名称提示
}

属性说明 #

属性	类型	必需	描述
name	string	否	模型名称提示。客户端应将其视为模型名称的子字符串。例如：claude-3-5-sonnet应该匹配claude-3-5-sonnet-20241022

6.3 ModelPreferences（模型偏好） #

服务器在采样期间向客户端请求的模型选择偏好。由于LLMs在多个维度上可能存在差异，选择"最佳"模型往往并不简单。该接口允许服务器在多个维度上表达其优先级，帮助客户端根据具体使用场景做出合适的选择。

interface ModelPreferences {
  costPriority?: number;                      // 成本优先级
  hints?: ModelHint[];                       // 提示
  intelligencePriority?: number;              // 智能优先级
  speedPriority?: number;                    // 速度优先级
}

属性说明 #

属性	类型	必需	描述
costPriority	number	否	在选择模型时应将成本置于何种优先级。数值0表示成本不重要，而数值1表示成本是最重要的考量因素
hints	ModelHint[]	否	用于模型选择的可选提示。如果指定了多个提示，客户端必须按顺序评估它们
intelligencePriority	number	否	在选择模型时，对智能和能力的重视程度应设定为多少。值为0表示智能不重要，而值为1表示智能是最重要的考量因素
speedPriority	number	否	在选择模型时，对采样速度（延迟）的优先级设置。数值0表示速度不重要，而数值1表示速度是最关键的因素

7. JSON Schema 类型 #

7.1 NumberSchema（数字模式） #

数字值的JSON Schema定义。

interface NumberSchema {
  description?: string;                       // 描述
  maximum?: number;                          // 最大值
  minimum?: number;                          // 最小值
  title?: string;                            // 标题
  type: "number" | "integer";                // 类型
}

属性说明 #

属性	类型	必需	描述
description	string	否	字段的描述信息
maximum	number	否	数字的最大值
minimum	number	否	数字的最小值
title	string	否	字段的标题
type	`"number" \	"integer"`	是	数字类型，可以是"number"或"integer"

7.2 PrimitiveSchemaDefinition（原始模式定义） #

仅允许基本类型且不允许嵌套对象或数组的受限模式定义。

type PrimitiveSchemaDefinition = 
  | StringSchema
  | NumberSchema
  | BooleanSchema
  | EnumSchema;

7.3 ProgressToken（进度Access Token） #

一个进度Access Token，用于将进度通知与原始请求关联起来。

type ProgressToken = string | number;

8.🎯 提示相关类型 #

8.1 Prompt（提示） #

服务器提供的提示或提示模板。

interface Prompt {
  _meta?: { [key: string]: unknown };       // 元数据
  arguments?: PromptArgument[];              // 参数
  description?: string;                      // 描述
  name: string;                             // 名称
  title?: string;                           // 标题
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段，请参阅规范了解使用说明
arguments	PromptArgument[]	否	用于模板化提示的参数列表
description	string	否	提示的描述信息
name	string	是	提示的名称
title	string	否	提示的标题

9.🎯 提示和资源相关类型 #

9.1 PromptArgument（提示参数） #

描述一个prompt可以接受的参数。

interface PromptArgument {
  description?: string;                       // 描述
  name: string;                              // 名称
  required?: boolean;                         // 必需
  title?: string;                            // 标题
}

属性说明 #

属性	类型	必需	描述
description	string	否	参数的人类可读描述
name	string	是	参数名称，用于编程或逻辑用途
required	boolean	否	此参数是否必须提供
title	string	否	专为UI界面和终端用户场景设计的标题

9.2 PromptMessage（提示消息） #

描述作为提示的一部分返回的消息。这与SamplingMessage类似，同时也支持嵌入来自MCP服务器的资源。

interface PromptMessage {
  content: ContentBlock;                      // 内容
  role: Role;                                // 角色
}

属性说明 #

属性	类型	必需	描述
content	ContentBlock	是	消息内容，可以是文本、图像、音频、资源链接或嵌入式资源
role	Role	是	消息的角色（如"user"、"assistant"等）

9.3 PromptReference（提示参考） #

标识一个提示。

interface PromptReference {
  name: string;                              // 名称
  title?: string;                            // 标题
  type: "ref/prompt";                        // 类型
}

属性说明 #

属性	类型	必需	描述
name	string	是	提示的名称
title	string	否	提示的标题，专为UI界面设计
type	"ref/prompt"	是	固定值"ref/prompt"

9.4 RequestId（请求ID） #

JSON-RPC请求的唯一标识ID。

type RequestId = string | number;

10.📁 资源相关类型 #

10.1 Resource（资源） #

服务器能够读取的已知资源。

interface Resource {
  _meta?: { [key: string]: unknown };       // 元数据
  annotations?: Annotations;                 // 注解
  description?: string;                      // 描述
  mimeType?: string;                        // MIME类型
  name: string;                             // 名称
  size?: number;                            // 大小
  title?: string;                           // 标题
  uri: string;                              // URI
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段，请参阅规范了解使用说明
annotations	Annotations	否	客户端的可选注解
description	string	否	该资源所代表内容的描述。客户端可以利用这一点来增强LLM对可用资源的理解
mimeType	string	否	此资源的MIME类型（如已知）
name	string	是	资源名称，用于编程或逻辑用途
size	number	否	原始资源内容的大小，以字节为单位（如果已知）
title	string	否	专为UI和终端用户场景设计的标题
uri	string	是	此资源的URI

10.2 ResourceContents（资源内容） #

特定资源或子资源的内容。

interface ResourceContents {
  _meta?: { [key: string]: unknown };       // 元数据
  mimeType?: string;                        // MIME类型
  uri: string;                              // URI
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段，请参阅规范了解使用说明
mimeType	string	否	此资源的MIME类型（如果已知）
uri	string	是	此资源的URI

10.3 ResourceLink（资源链接） #

服务器能够读取的资源，包含在提示或工具调用结果中。注意：工具返回的资源链接不保证出现在resources/list请求的结果中。

interface ResourceLink {
  _meta?: { [key: string]: unknown };       // 元数据
  annotations?: Annotations;                 // 注解
  description?: string;                      // 描述
  mimeType?: string;                        // MIME类型
  name: string;                             // 名称
  size?: number;                            // 大小
  title?: string;                           // 标题
  type: "resource";                         // 类型
  uri: string;                              // URI
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段，请参阅规范了解使用说明
annotations	Annotations	否	客户端的可选注解
description	string	否	该资源所代表内容的描述
mimeType	string	否	此资源的MIME类型（如已知）
name	string	是	资源名称
size	number	否	原始资源内容的大小，以字节为单位（如果已知）
title	string	否	专为UI和终端用户场景设计的标题
type	"resource"	是	固定值"resource"
uri	string	是	此资源的URI

10.4 ResourceTemplate（资源模板） #

服务器上可用资源的模板描述。

interface ResourceTemplate {
  _meta?: { [key: string]: unknown };       // 元数据
  annotations?: Annotations;                 // 注解
  description?: string;                      // 描述
  mimeType?: string;                        // MIME类型
  name: string;                             // 名称
  title?: string;                           // 标题
  uriTemplate: string;                      // URI模板
}

属性说明 #

属性	类型	必需	描述
_meta	{ [key: string]: unknown }	否	元数据字段，请参阅规范了解使用说明
annotations	Annotations	否	客户端的可选注解
description	string	否	此模板用途的说明
mimeType	string	否	此资源的MIME类型（如已知）
name	string	是	模板名称
title	string	否	专为UI和终端用户场景设计的标题
uriTemplate	string	是	资源的URI模板

11. 总结 #

本文档提供了Model Context Protocol (MCP) 的完整架构参考，包括：

11.1 🔧 基础类型 #

• Annotations - 客户端注解
• AudioContent - 音频内容
• BinaryContent - 二进制内容
• ImageContent - 图像内容
• TextContent - 文本内容

11.2 📨 JSON-RPC消息类型 #

• JSONRPCRequest - 请求消息
• JSONRPCResponse - 响应消息
• JSONRPCNotification - 通知消息
• JSONRPCError - 错误消息

11.3 🎯 功能相关类型 #

• Capabilities - 服务器能力
• ClientCapabilities - 客户端能力
• ModelPreferences - 模型偏好
• LoggingLevel - 日志级别

11.4 📁 资源相关类型 #

• Resource - 资源定义
• ResourceContents - 资源内容
• ResourceLink - 资源链接
• ResourceTemplate - 资源模板

11.5 🎯 提示相关类型 #

• Prompt - 提示定义
• PromptArgument - 提示参数
• PromptMessage - 提示消息
• PromptReference - 提示参考

11.6 Schema类型 #

• BooleanSchema - 布尔模式
• NumberSchema - 数字模式
• StringSchema - 字符串模式
• EnumSchema - 枚举模式