JSON-RPC
JSONRPCErrorResponse
JSONRPCMessage
指任何可从传输线上解码或编码后发送的有效 JSON-RPC 对象。
JSONRPCNotification
不期望响应的通知。
JSONRPCRequest
method: string;
params?: { [key: string]: any };
jsonrpc: “2.0”;
id: RequestId;
}
期望响应的请求。
JSONRPCResultResponse
对请求的成功(非错误)响应。
通用类型
Annotations
供客户端使用的可选注释。客户端可以使用注释来辅助决定对象如何被使用或显示。
描述此对象或数据的预期受众。
可包含多个条目,用于表示内容对多个受众有用(例如 [“user”, “assistant”])。
描述此数据对服务器运行的重要程度。
值为 1 表示“最重要”,并表示该数据实际上是必需的;值为 0 表示“最不重要”,并表示该数据完全可选。
资源最后一次修改的时间,以 ISO 8601 格式字符串表示。
应为 ISO 8601 格式字符串(例如 “2025-01-12T15:00:58Z”)。
示例:打开文件中的最后活动时间戳、资源附加时的时间戳等。
Icon
可在用户界面中显示、可选指定尺寸的图标。
指向图标资源的标准 URI。可以是 HTTP/HTTPS URL,也可以是带有 Base64 编码图像数据的 data: URI。
使用方 SHOULD 采取措施,确保提供图标的 URL 来自与客户端/服务器相同的域或受信任域。
使用方在使用 SVG 时 SHOULD 采取适当的预防措施,因为 SVG 可能包含可执行 JavaScript。
当源 MIME 类型缺失或过于宽泛时,可选地覆盖 MIME 类型。例如:“image/png”、“image/jpeg” 或 “image/svg+xml”。
可选的字符串数组,用于指定图标可使用的尺寸。每个字符串应采用 WxH 格式(例如 “48x48”、“96x96”),对于 SVG 等可缩放格式则使用 “any”。
如果未提供,客户端应假定该图标可用于任意尺寸。
可选说明此图标设计面向的主题。“light” 表示该图标设计用于浅色背景,“dark” 表示该图标设计用于深色背景。
如果未提供,客户端应假定该图标可用于任何主题。
InputResponseRequestParams
_meta: RequestMetaObject;
inputResponses?: InputResponses;
requestState?: string;
}
任何请求的通用参数。
JSONValue
LoggingLevel
| “debug”
| “info”
| “notice”
| “warning”
| “error”
| “critical”
| “alert”
| “emergency”
日志消息的严重级别。
这些级别映射到 RFC-5424 中规定的 syslog 消息严重级别:https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
MetaObject
表示 _meta 字段的内容,客户端和服务器使用该字段为其交互附加额外元数据。
某些键名由 MCP 保留用于协议级元数据;实现 MUST NOT 对这些键上的值作出假设。此外,特定 schema 定义可按其声明为特定用途的元数据保留特定名称。
有效键包含两个部分:
前缀:
- 可选 — 如果指定,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])开头和结尾。 - 内部字符可以是字母数字字符、连字符(
-)、下划线(_)或点(.)。
更多详情请参见通用字段:_meta。
PaginatedRequestParams
分页请求的通用参数。
表示当前分页位置的不透明令牌。如果提供,服务器应返回从该游标之后开始的结果。
RequestMetaObject
progressToken?: ProgressToken;
“io.modelcontextprotocol/protocolVersion”: string;
“io.modelcontextprotocol/clientInfo”: Implementation;
“io.modelcontextprotocol/clientCapabilities”: ClientCapabilities;
“io.modelcontextprotocol/logLevel”?: LoggingLevel;
[key: string]: unknown;
}
使用额外的请求专用字段扩展 MetaObject。MetaObject 的所有键命名规则均适用。
- MetaObject,用于了解键命名规则和保留前缀。
- 通用字段:
_meta,用于了解更多详情。
如果指定,调用方请求接收此请求的带外进度通知(由 notifications/progress 表示)。该参数的值是不透明令牌,将附加到任何后续通知中。接收方没有义务提供这些通知。
此请求使用的 MCP 协议版本。必需。
对于 HTTP 传输,此值 MUST 与 MCP-Protocol-Version 标头匹配;否则服务器 MUST 返回 400 Bad Request。如果服务器不支持请求的版本,则 MUST 返回 UnsupportedProtocolVersionError。
标识发出请求的客户端软件。必需。
Implementation schema 要求包含 name 和 version;其他字段可选。
客户端针对此特定请求的能力。必需。
能力按请求声明,而不是在初始化时只声明一次;空对象表示客户端不支持任何可选能力。服务器 MUST NOT 根据之前的请求推断能力。
此请求期望的日志级别。可选。
如果不存在,服务器 MUST NOT 为此请求发送任何 notifications/message 通知。客户端通过显式设置级别来选择接收日志消息。取代以前的 logging/setLevel RPC。
自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
RequestParams
任何请求的通用参数。
Result
通用结果字段。
表示结果的类型,使客户端能够确定如何解析结果对象。
实现此协议版本的服务器 MUST 包含此字段。为了向后兼容,当客户端从实现较早协议版本的服务器收到结果(其中不包含 resultType)时,客户端 MUST 将缺失字段视为 “complete”。
ResultType
表示 Result 对象的类型,使客户端能够确定如何解析响应。
complete - 请求已成功完成,结果包含最终内容。 input_required - 请求需要额外输入,结果包含一个 InputRequiredResult 对象,其中包含让客户端在重试原始请求前提供额外输入的指令。
错误
Error
发生的错误类型。
错误的简短描述。消息 SHOULD 限制为简洁的单句。
关于错误的附加信息。此成员的值由发送方定义(例如详细错误信息、嵌套错误等)。
InternalError
表示接收方发生内部错误的 JSON-RPC 错误。当接收方遇到阻止其完成请求的意外状况时返回此错误。
错误的简短描述。消息 SHOULD 限制为简洁的单句。
关于错误的附加信息。此成员的值由发送方定义(例如详细错误信息、嵌套错误等)。
发生的错误类型。
InvalidParamsError
表示方法参数无效或格式不正确的 JSON-RPC 错误。
在 MCP 中,当请求参数验证失败时,会在多种上下文中返回此错误:
- 工具:未知工具名称或无效工具参数
- 提示:未知提示名称或缺少必需参数
- 分页:无效或过期的游标值
- 日志:无效日志级别
- 引出:服务器请求了客户端能力中未声明的引出模式
- 采样:缺少工具结果,或工具结果与其他内容混合
错误的简短描述。消息 SHOULD 限制为简洁的单句。
关于错误的附加信息。此成员的值由发送方定义(例如详细错误信息、嵌套错误等)。
发生的错误类型。
InvalidRequestError
表示请求不是有效请求对象的 JSON-RPC 错误。当消息结构不符合 JSON-RPC 2.0 规范对请求的要求时返回此错误(例如缺少 jsonrpc 或 method 等必需字段,或这些字段使用了无效类型)。
错误的简短描述。消息 SHOULD 限制为简洁的单句。
关于错误的附加信息。此成员的值由发送方定义(例如详细错误信息、嵌套错误等)。
发生的错误类型。
MethodNotFoundError
表示所请求方法不存在或不可用的 JSON-RPC 错误。
在 MCP 中,当客户端调用服务器未实现的方法时,服务器会返回此错误——该方法可能是真正未知的方法,也可能受服务器未声明的能力限制(例如在未声明 prompts 能力时调用 prompts/list)。
如果请求需要客户端未声明的客户端能力,则改用 MissingRequiredClientCapabilityError(-32003)表示。
错误的简短描述。消息 SHOULD 限制为简洁的单句。
关于错误的附加信息。此成员的值由发送方定义(例如详细错误信息、嵌套错误等)。
发生的错误类型。
MISSING_REQUIRED_CLIENT_CAPABILITY
当服务器需要某项客户端能力,而该能力未在请求的 clientCapabilities 中声明时返回的错误代码。
MissingRequiredClientCapabilityError
jsonrpc: “2.0”;
id?: RequestId;
error: Error & {
code: -32003;
data: { requiredCapabilities: ClientCapabilities };
};
}
当处理请求需要客户端未在 clientCapabilities 中声明的能力时返回。对于 HTTP,响应状态码 MUST 为 400 Bad Request。
ParseError
表示服务器收到了无效 JSON 的 JSON-RPC 错误。当服务器无法解析消息的 JSON 文本时返回此错误。
错误的简短描述。消息 SHOULD 限制为简洁的单句。
关于错误的附加信息。此成员的值由发送方定义(例如详细错误信息、嵌套错误等)。
发生的错误类型。
UnsupportedProtocolVersionError
jsonrpc: “2.0”;
id?: RequestId;
error: Error & {
code: -32004;
data: { supported: string[]; requested: string };
};
}
当请求的协议版本对服务器未知或不受支持时返回(例如服务器选择不实现的已知实验版或草案版本)。对于 HTTP,响应状态码 MUST 为 400 Bad Request。
内容
AudioContent
type: “audio”;
data: string;
mimeType: string;
annotations?: Annotations;
_meta?: MetaObject;
}
提供给 LLM 或由 LLM 提供的音频。
Base64 编码的音频数据。
音频的 MIME 类型。不同提供商可能支持不同的音频类型。
供客户端使用的可选注释。
BlobResourceContents
此资源的 URI。
此资源的 MIME 类型(如果已知)。
表示该项二进制数据的 Base64 编码字符串。
ContentBlock
EmbeddedResource
type: “resource”;
resource: TextResourceContents | BlobResourceContents;
annotations?: Annotations;
_meta?: MetaObject;
}
嵌入到提示或工具调用结果中的资源内容。
客户端自行决定如何最佳地渲染嵌入资源,以便 LLM 和/或用户使用。
供客户端使用的可选注释。
ImageContent
type: “image”;
data: string;
mimeType: string;
annotations?: Annotations;
_meta?: MetaObject;
}
提供给 LLM 或由 LLM 提供的图像。
Base64 编码的图像数据。
图像的 MIME 类型。不同提供商可能支持不同的图像类型。
供客户端使用的可选注释。
ResourceLink
icons?: Icon[];
name: string;
title?: string;
uri: string;
description?: string;
mimeType?: string;
annotations?: Annotations;
size?: number;
_meta?: MetaObject;
type: “resource_link”;
}
服务器能够读取并包含在提示或工具调用结果中的资源。
注意:工具返回的资源链接不保证会出现在 resources/list 请求的结果中。
客户端可在用户界面中显示的一组带尺寸图标,可选。
支持渲染图标的客户端 MUST 至少支持以下 MIME 类型:
image/png- PNG 图像(安全,通用兼容)image/jpeg(以及image/jpg)- JPEG 图像(安全,通用兼容)
支持渲染图标的客户端 SHOULD 也支持:
image/svg+xml- SVG 图像(可缩放但需要安全预防措施)image/webp- WebP 图像(现代、高效格式)
用于程序化或逻辑用途,但在以往规范或回退场景中(如果 title 不存在)也用作显示名称。
用于 UI 和最终用户上下文——优化为人类可读且易于理解,即使读者不熟悉特定领域术语。
如果未提供,应使用 name 进行显示(但对于 Tool,如果存在 annotations.title,则应优先于 name 使用)。
此资源的 URI。
对此资源所表示内容的描述。
客户端可使用此信息改进 LLM 对可用资源的理解。可将其视为给模型的“提示”。
此资源的 MIME 类型(如果已知)。
供客户端使用的可选注释。
原始资源内容的大小(以字节为单位,即 Base64 编码或任何分词之前),如果已知。
Host 可使用此信息显示文件大小并估算上下文窗口使用量。
TextContent
提供给 LLM 或由 LLM 提供的文本。
消息的文本内容。
供客户端使用的可选注释。
TextResourceContents
此资源的 URI。
此资源的 MIME 类型(如果已知)。
该项的文本。仅当该项确实可以表示为文本(而非二进制数据)时才必须设置。
completion/complete
CompleteRequest
jsonrpc: “2.0”;
id: RequestId;
method: “completion/complete”;
params: CompleteRequestParams;
}
客户端发送给服务器、用于请求补全选项的请求。
示例:补全请求
{
“jsonrpc”: “2.0”,
“id”: “completion-example”,
“method”: “completion/complete”,
“params”: {
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
},
“ref”: {
“type”: “ref/prompt”,
“name”: “code_review”
},
“argument”: {
“name”: “language”,
“value”: “py”
}
}
} CompleteRequestParams
_meta: RequestMetaObject;
ref: PromptReference | ResourceTemplateReference;
argument: { name: string; value: string };
context?: { arguments?: { [key: string]: string } };
}
completion/complete 请求的参数。
示例:提示参数补全
{
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
},
“ref”: {
“type”: “ref/prompt”,
“name”: “code_review”
},
“argument”: {
“name”: “language”,
“value”: “py”
}
} 示例:带上下文的提示参数补全
{
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
},
“ref”: {
“type”: “ref/prompt”,
“name”: “code_review”
},
“argument”: {
“name”: “framework”,
“value”: “fla”
},
“context”: {
“arguments”: {
“language”: “python”
}
}
} 参数的信息。
- name: string
参数的名称。
- value: string
用于补全匹配的参数值。
用于补全的额外可选上下文。
Optionalarguments?: { [key: string]: string }URI 模板或提示中先前已解析的变量。
CompleteResult
_meta?: MetaObject;
resultType: string;
completion: { values: string[]; total?: number; hasMore?: boolean };
[key: string]: unknown;
}
服务器针对 completion/complete 请求返回的结果。
表示结果的类型,使客户端能够确定如何解析结果对象。
实现此协议版本的服务器 MUST 包含此字段。为了向后兼容,当客户端从实现较早协议版本的服务器收到结果(其中不包含 resultType)时,客户端 MUST 将缺失字段视为 “complete”。
- values: string[]
补全值数组。不得超过 100 项。
Optionaltotal?: number可用补全选项总数。该数量可能超过响应中实际发送的值数量。
OptionalhasMore?: boolean表示除当前响应中提供的补全选项外是否还有更多选项,即使确切总数未知。
PromptReference
标识一个提示。
用于程序化或逻辑用途,但在以往规范或回退场景中(如果 title 不存在)也用作显示名称。
用于 UI 和最终用户上下文——优化为人类可读且易于理解,即使读者不熟悉特定领域术语。
如果未提供,应使用 name 进行显示(但对于 Tool,如果存在 annotations.title,则应优先于 name 使用)。
ResourceTemplateReference
对资源或资源模板定义的引用。
资源的 URI 或 URI 模板。
elicitation/create
ElicitRequest
服务器通过客户端向用户引出额外信息的请求。
ElicitRequestParams
通过客户端向用户引出额外信息的请求参数。
ElicitResult
action: “accept” | “decline” | “cancel”;
content?: { [key: string]: string | number | boolean | string[] };
}
客户端针对 elicitation/create 请求返回的结果。
示例:输入多个字段
{
“action”: “accept”,
“content”: {
“name”: “Monalisa Octocat”,
“email”: “octocat@github.com”,
“age”: 30
}
} 用户对引出的响应动作。
“accept”:用户提交了表单/确认了操作“decline”:用户明确拒绝了操作“cancel”:用户在未作出明确选择的情况下关闭
提交的表单数据,仅在 action 为 “accept” 且 mode 为 “form” 时存在。包含与请求 schema 匹配的值。对于带外模式响应则省略。
BooleanSchema
type: “boolean”;
title?: string;
description?: string;
default?: boolean;
}
ElicitRequestFormParams
mode?: “form”;
message: string;
requestedSchema: {
$schema?: string;
type: “object”;
properties: { [key: string]: PrimitiveSchemaDefinition };
required?: string[];
};
}
通过客户端中的表单向用户引出非敏感信息的请求参数。
示例:引出单个字段
{
“mode”: “form”,
“message”: “Please provide your GitHub username”,
“requestedSchema”: {
“type”: “object”,
“properties”: {
“name”: {
“type”: “string”
}
},
“required”: [“name”]
}
} 示例:引出多个字段
{
“mode”: “form”,
“message”: “Please provide your contact information”,
“requestedSchema”: {
“type”: “object”,
“properties”: {
“name”: {
“type”: “string”,
“description”: “Your full name”
},
“email”: {
“type”: “string”,
“format”: “email”,
“description”: “Your email address”
},
“age”: {
“type”: “number”,
“minimum”: 18,
“description”: “Your age”
}
},
“required”: [“name”, “email”]
}
} 引出模式。
向用户展示的消息,用于描述正在请求哪些信息。
JSON Schema 的受限子集。仅允许顶层属性,不允许嵌套。
ElicitRequestURLParams
mode: “url”;
message: string;
elicitationId: string;
url: string;
}
通过客户端中的 URL 向用户引出信息的请求参数。
示例:引出敏感数据
{
“mode”: “url”,
“elicitationId”: “550e8400-e29b-41d4-a716-446655440000”,
“url”: “https://mcp.example.com/ui/set_api_key”,
“message”: “Please provide your API key to continue.”
} 引出模式。
向用户展示的消息,用于解释为什么需要此次交互。
引出的 ID,在服务器上下文中必须唯一。客户端 MUST 将此 ID 视为不透明值。
用户应导航到的 URL。
EnumSchema
LegacyTitledEnumSchema
type: “string”;
title?: string;
description?: string;
enum: string[];
enumNames?: string[];
default?: string;
}
请改用 TitledSingleSelectEnumSchema。此接口将在未来版本中移除。
(旧版)枚举值的显示名称。根据 JSON Schema 2020-12,这不是标准用法。
MultiSelectEnumSchema
NumberSchema
type: “number” | “integer”;
title?: string;
description?: string;
minimum?: number;
maximum?: number;
default?: number;
}
PrimitiveSchemaDefinition
受限的 schema 定义,仅允许原始类型,不包含嵌套对象或数组。
SingleSelectEnumSchema
StringSchema
type: “string”;
title?: string;
description?: string;
minLength?: number;
maxLength?: number;
format?: “uri” | “email” | “date” | “date-time”;
default?: string;
}
示例:电子邮件输入 schema
{
“type”: “string”,
“title”: “Display Name”,
“description”: “Description text”,
“minLength”: 3,
“maxLength”: 50,
“format”: “email”,
“default”: “user@example.com”
} TitledMultiSelectEnumSchema
type: “array”;
title?: string;
description?: string;
minItems?: number;
maxItems?: number;
items: { anyOf: { const: string; title: string }[] };
default?: string[];
}
多选枚举的 schema,每个选项都有显示标题。
示例:带标题的颜色多选 schema
{
“type”: “array”,
“title”: “Color Selection”,
“description”: “Choose your favorite colors”,
“minItems”: 1,
“maxItems”: 2,
“items”: {
“anyOf”: [
{ “const”: “#FF0000”, “title”: “Red” },
{ “const”: “#00FF00”, “title”: “Green” },
{ “const”: “#0000FF”, “title”: “Blue” }
]
},
“default”: [“#FF0000”, “#00FF00”]
} 枚举字段的可选标题。
枚举字段的可选描述。
要选择的最少项数。
要选择的最多项数。
数组项的 schema,包含枚举选项和显示标签。
- anyOf: { const: string; title: string }[]
包含值和显示标签的枚举选项数组。
可选默认值。
TitledSingleSelectEnumSchema
type: “string”;
title?: string;
description?: string;
oneOf: { const: string; title: string }[];
default?: string;
}
单选枚举的 schema,每个选项都有显示标题。
枚举字段的可选标题。
枚举字段的可选描述。
包含值和显示标签的枚举选项数组。
- const: string
枚举值。
- title: string
此选项的显示标签。
可选默认值。
UntitledMultiSelectEnumSchema
type: “array”;
title?: string;
description?: string;
minItems?: number;
maxItems?: number;
items: { type: “string”; enum: string[] };
default?: string[];
}
不带选项显示标题的多选枚举 schema。
枚举字段的可选标题。
枚举字段的可选描述。
要选择的最少项数。
要选择的最多项数。
数组项的 schema。
- type: “string”
- enum: string[]
可供选择的枚举值数组。
可选默认值。
UntitledSingleSelectEnumSchema
type: “string”;
title?: string;
description?: string;
enum: string[];
default?: string;
}
不带选项显示标题的单选枚举 schema。
枚举字段的可选标题。
枚举字段的可选描述。
可供选择的枚举值数组。
可选默认值。
notifications/cancelled
CancelledNotification
jsonrpc: “2.0”;
method: “notifications/cancelled”;
params: CancelledNotificationParams;
}
任一方都可以发送此通知,表示正在取消先前发出的请求。
该请求 SHOULD 仍处于进行中,但由于通信延迟,此通知始终 MAY 在请求已经完成后到达。
此通知表示结果将不会被使用,因此任何相关处理 SHOULD 停止。
CancelledNotificationParams
_meta?: MetaObject;
requestId?: RequestId;
reason?: string;
}
notifications/cancelled 通知的参数。
要取消的请求 ID。
这 MUST 对应同一方向上先前发出请求的 ID。
描述取消原因的可选字符串。该字符串 MAY 被记录或展示给用户。
notifications/message
LoggingMessageNotification
jsonrpc: “2.0”;
method: “notifications/message”;
params: LoggingMessageNotificationParams;
}
从服务器传递给客户端的日志消息 JSONRPCNotification。客户端通过在请求的 _meta 中设置 “io.modelcontextprotocol/logLevel” 来选择接收。
自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
LoggingMessageNotificationParams
_meta?: MetaObject;
level: LoggingLevel;
logger?: string;
data: unknown;
}
notifications/message 通知的参数。
自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
此日志消息的严重级别。
发出此消息的日志记录器的可选名称。
要记录的数据,例如字符串消息或对象。这里允许任何可 JSON 序列化的类型。
notifications/progress
ProgressNotification
jsonrpc: “2.0”;
method: “notifications/progress”;
params: ProgressNotificationParams;
}
用于向接收方告知长时间运行请求进度更新的带外通知。
ProgressNotificationParams
_meta?: MetaObject;
progressToken: ProgressToken;
progress: number;
total?: number;
message?: string;
}
notifications/progress 通知的参数。
初始请求中给出的进度令牌,用于将此通知与正在进行的请求关联。
到目前为止的进度。即使总量未知,每次取得进展时该值也应增加。
要处理的总项数(或所需总进度),如果已知。
描述当前进度的可选消息。
notifications/prompts/list_changed
PromptListChangedNotification
jsonrpc: “2.0”;
method: “notifications/prompts/list_changed”;
params?: NotificationParams;
}
服务器发送给客户端的可选通知,告知其提供的提示列表已更改。服务器可以在客户端没有任何先前订阅的情况下发出此通知。
notifications/resources/list_changed
ResourceListChangedNotification
jsonrpc: “2.0”;
method: “notifications/resources/list_changed”;
params?: NotificationParams;
}
服务器发送给客户端的可选通知,告知其可读取的资源列表已更改。服务器可以在客户端没有任何先前订阅的情况下发出此通知。
notifications/resources/updated
ResourceUpdatedNotification
jsonrpc: “2.0”;
method: “notifications/resources/updated”;
params: ResourceUpdatedNotificationParams;
}
服务器发送给客户端的通知,告知某个资源已更改并且可能需要重新读取。仅针对客户端通过 subscriptions/listen 请求中的 resourceSubscriptions 字段选择接收的资源发送。
ResourceUpdatedNotificationParams
notifications/resources/updated 通知的参数。
已更新资源的 URI。这可能是客户端实际订阅资源的子资源。
notifications/subscriptions/acknowledged
SubscriptionsAcknowledgedNotification
jsonrpc: “2.0”;
method: “notifications/subscriptions/acknowledged”;
params: SubscriptionsAcknowledgedNotificationParams;
}
由服务器作为 subscriptions/listen 流上的第一条消息发送,用于确认订阅已建立,并报告其同意履行哪些通知类型。
SubscriptionsAcknowledgedNotificationParams
_meta?: MetaObject;
notifications: SubscriptionFilter;
}
服务器同意履行的请求通知类型子集。仅包含服务器实际支持的通知类型;如果客户端请求了不支持的类型(例如服务器没有提示时的 promptsListChanged),该类型会从此集合中省略。
notifications/tools/list_changed
ToolListChangedNotification
jsonrpc: “2.0”;
method: “notifications/tools/list_changed”;
params?: NotificationParams;
}
服务器发送给客户端的可选通知,告知其提供的工具列表已更改。服务器可以在客户端没有任何先前订阅的情况下发出此通知。
notifications/elicitation/complete
ElicitationCompleteNotification
jsonrpc: “2.0”;
method: “notifications/elicitation/complete”;
params: ElicitationCompleteNotificationParams;
}
服务器发送给客户端的可选通知,告知带外引出请求已完成。
ElicitationCompleteNotificationParams
已完成引出的 ID。
多轮往返
InputRequests
客户端必须满足的服务器发起请求映射。键是服务器分配的标识符;值是请求对象。
示例:引出和采样输入请求
{
“github_login”: {
“method”: “elicitation/create”,
“params”: {
“mode”: “form”,
“message”: “Please provide your GitHub username”,
“requestedSchema”: {
“type”: “object”,
“properties”: {
“name”: {
“type”: “string”
}
},
“required”: [“name”]
}
}
},
“capital_of_france”: {
“method”: “sampling/createMessage”,
“params”: {
“messages”: [
{
“role”: “user”,
“content”: {
“type”: “text”,
“text”: “What is the capital of France?”
}
}
],
“maxTokens”: 100
}
}
} InputRequiredResult
_meta?: MetaObject;
resultType: string;
inputRequests?: InputRequests;
requestState?: string;
[key: string]: unknown;
}
服务器发送的 InputRequiredResult,表示在请求完成前需要额外输入。
inputRequests 或 requestState 中至少一个 MUST 存在。
示例:带引出和采样输入请求及请求状态的 InputRequiredResult
{
“resultType”: “input_required”,
“inputRequests”: {
“github_login”: {
“method”: “elicitation/create”,
“params”: {
“message”: “Please provide your GitHub username”,
“requestedSchema”: {
“type”: “object”,
“properties”: {
“name”: {
“type”: “string”
}
},
“required”: [“name”]
}
}
},
“capital_of_france”: {
“method”: “sampling/createMessage”,
“params”: {
“messages”: [
{
“role”: “user”,
“content”: {
“type”: “text”,
“text”: “What is the capital of France?”
}
}
],
“maxTokens”: 100
}
}
},
“requestState”: “eyJsb2NhdGlvbiI6Ik5ldyBZb3JrIn0”
} 表示结果的类型,使客户端能够确定如何解析结果对象。
实现此协议版本的服务器 MUST 包含此字段。为了向后兼容,当客户端从实现较早协议版本的服务器收到结果(其中不包含 resultType)时,客户端 MUST 将缺失字段视为 “complete”。
prompts/get
GetPromptRequest
jsonrpc: “2.0”;
id: RequestId;
method: “prompts/get”;
params: GetPromptRequestParams;
}
客户端用于获取服务器提供的提示。
示例:获取提示请求
{
“jsonrpc”: “2.0”,
“id”: “get-prompt-example”,
“method”: “prompts/get”,
“params”: {
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
},
“name”: “code_review”,
“arguments”: {
“code”: “def hello():\n print(‘world’)”
}
}
} GetPromptRequestParams
_meta: RequestMetaObject;
inputResponses?: InputResponses;
requestState?: string;
name: string;
arguments?: { [key: string]: string };
}
prompts/get 请求的参数。
示例:获取代码审查提示
{
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
},
“name”: “code_review”,
“arguments”: {
“code”: “def hello():\n print(‘world’)”
}
} 提示或提示模板的名称。
用于模板化提示的参数。
GetPromptResultResponse
jsonrpc: “2.0”;
id: RequestId;
result: InputRequiredResult | GetPromptResult;
}
服务器针对 prompts/get 请求返回的成功响应。
GetPromptResult
_meta?: MetaObject;
resultType: string;
description?: string;
messages: PromptMessage[];
[key: string]: unknown;
}
服务器针对 prompts/get 请求返回的结果。
表示结果的类型,使客户端能够确定如何解析结果对象。
实现此协议版本的服务器 MUST 包含此字段。为了向后兼容,当客户端从实现较早协议版本的服务器收到结果(其中不包含 resultType)时,客户端 MUST 将缺失字段视为 “complete”。
提示的可选描述。
prompts/list
ListPromptsRequest
jsonrpc: “2.0”;
id: RequestId;
params: PaginatedRequestParams;
method: “prompts/list”;
}
客户端发送,用于请求服务器拥有的提示和提示模板列表。
示例:列出提示请求
{
“jsonrpc”: “2.0”,
“id”: “list-prompts-example”,
“method”: “prompts/list”,
“params”: {
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
}
}
} ListPromptsResultResponse
服务器针对 prompts/list 请求返回的成功响应。
示例:列出提示结果响应
{
“jsonrpc”: “2.0”,
“id”: “list-prompts-example”,
“result”: {
“resultType”: “complete”,
“prompts”: [
{
“name”: “code_review”,
“title”: “Request Code Review”,
“description”: “Asks the LLM to analyze code quality and suggest improvements”,
“arguments”: [
{
“name”: “code”,
“description”: “The code to review”,
“required”: true
}
],
“icons”: [
{
“src”: “https://example.com/review-icon.svg”,
“mimeType”: “image/svg+xml”,
“sizes”: [“any”]
}
]
}
],
“nextCursor”: “next-page-cursor”,
“ttlMs”: 600000,
“cacheScope”: “public”
}
} ListPromptsResult
_meta?: MetaObject;
resultType: string;
nextCursor?: string;
ttlMs: number;
cacheScope: “public” | “private”;
prompts: Prompt[];
[key: string]: unknown;
}
服务器针对 prompts/list 请求返回的结果。
示例:带游标和 TTL 的提示列表
{
“resultType”: “complete”,
“prompts”: [
{
“name”: “code_review”,
“title”: “Request Code Review”,
“description”: “Asks the LLM to analyze code quality and suggest improvements”,
“arguments”: [
{
“name”: “code”,
“description”: “The code to review”,
“required”: true
}
],
“icons”: [
{
“src”: “https://example.com/review-icon.svg”,
“mimeType”: “image/svg+xml”,
“sizes”: [“any”]
}
]
}
],
“nextCursor”: “next-page-cursor”,
“ttlMs”: 600000,
“cacheScope”: “public”
} 表示结果的类型,使客户端能够确定如何解析结果对象。
实现此协议版本的服务器 MUST 包含此字段。为了向后兼容,当客户端从实现较早协议版本的服务器收到结果(其中不包含 resultType)时,客户端 MUST 将缺失字段视为 “complete”。
表示最后一个返回结果之后分页位置的不透明令牌。如果存在,可能还有更多结果可用。
服务器提供的提示,表示客户端在重新获取前 MAY 缓存此响应多长时间(以毫秒为单位)。语义类似于 HTTP Cache-Control max-age。
- 如果为 0,响应 SHOULD 被视为立即过期;客户端 MAY 在每次需要结果时重新获取。
- 如果为正数,客户端 SHOULD 在收到响应后的这么多毫秒内将结果视为新鲜。
表示缓存响应的预期范围,类似于 HTTP Cache-Control: public 与 Cache-Control: private。
“public”:任何客户端或中介(例如共享网关、代理)MAY 缓存响应并将其提供给任何用户。“private”:只有发出请求用户的客户端 MAY 缓存响应。共享缓存(例如多租户网关)MUST NOT 将缓存副本提供给其他用户。
Prompt
icons?: Icon[];
name: string;
title?: string;
description?: string;
arguments?: PromptArgument[];
_meta?: MetaObject;
}
服务器提供的提示或提示模板。
客户端可在用户界面中显示的一组带尺寸图标,可选。
支持渲染图标的客户端 MUST 至少支持以下 MIME 类型:
image/png- PNG 图像(安全,通用兼容)image/jpeg(以及image/jpg)- JPEG 图像(安全,通用兼容)
支持渲染图标的客户端 SHOULD 也支持:
image/svg+xml- SVG 图像(可缩放但需要安全预防措施)image/webp- WebP 图像(现代、高效格式)
用于程序化或逻辑用途,但在以往规范或回退场景中(如果 title 不存在)也用作显示名称。
用于 UI 和最终用户上下文——优化为人类可读且易于理解,即使读者不熟悉特定领域术语。
如果未提供,应使用 name 进行显示(但对于 Tool,如果存在 annotations.title,则应优先于 name 使用)。
对此提示所提供内容的可选描述。
用于模板化提示的参数列表。
PromptArgument
描述提示可接受的参数。
用于程序化或逻辑用途,但在以往规范或回退场景中(如果 title 不存在)也用作显示名称。
用于 UI 和最终用户上下文——优化为人类可读且易于理解,即使读者不熟悉特定领域术语。
如果未提供,应使用 name 进行显示(但对于 Tool,如果存在 annotations.title,则应优先于 name 使用)。
参数的人类可读描述。
是否必须提供此参数。
resources/list
ListResourcesRequest
jsonrpc: “2.0”;
id: RequestId;
params: PaginatedRequestParams;
method: “resources/list”;
}
客户端发送,用于请求服务器拥有的资源列表。
示例:列出资源请求
{
“jsonrpc”: “2.0”,
“id”: “list-resources-example”,
“method”: “resources/list”,
“params”: {
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
}
}
} ListResourcesResultResponse
jsonrpc: “2.0”;
id: RequestId;
result: ListResourcesResult;
}
服务器针对 resources/list 请求返回的成功响应。
示例:列出资源结果响应
{
“jsonrpc”: “2.0”,
“id”: “list-resources-example”,
“result”: {
“resultType”: “complete”,
“resources”: [
{
“uri”: “file:///project/src/main.rs”,
“name”: “main.rs”,
“title”: “Rust Software Application Main File”,
“description”: “Primary application entry point”,
“mimeType”: “text/x-rust”,
“icons”: [
{
“src”: “https://example.com/rust-file-icon.png”,
“mimeType”: “image/png”,
“sizes”: [“48x48”]
}
]
}
],
“nextCursor”: “eyJwYWdlIjogM30=”,
“ttlMs”: 600000,
“cacheScope”: “private”
}
} ListResourcesResult
_meta?: MetaObject;
resultType: string;
nextCursor?: string;
ttlMs: number;
cacheScope: “public” | “private”;
resources: Resource[];
[key: string]: unknown;
}
服务器针对 resources/list 请求返回的结果。
示例:带游标和 TTL 的资源列表
{
“resultType”: “complete”,
“resources”: [
{
“uri”: “file:///project/src/main.rs”,
“name”: “main.rs”,
“title”: “Rust Software Application Main File”,
“description”: “Primary application entry point”,
“mimeType”: “text/x-rust”,
“icons”: [
{
“src”: “https://example.com/rust-file-icon.png”,
“mimeType”: “image/png”,
“sizes”: [“48x48”]
}
]
}
],
“nextCursor”: “eyJwYWdlIjogM30=”,
“ttlMs”: 600000,
“cacheScope”: “private”
} 表示结果的类型,使客户端能够确定如何解析结果对象。
实现此协议版本的服务器 MUST 包含此字段。为了向后兼容,当客户端从实现较早协议版本的服务器收到结果(其中不包含 resultType)时,客户端 MUST 将缺失字段视为 “complete”。
表示最后一个返回结果之后分页位置的不透明令牌。如果存在,可能还有更多结果可用。
服务器提供的提示,表示客户端在重新获取前 MAY 缓存此响应多长时间(以毫秒为单位)。语义类似于 HTTP Cache-Control max-age。
- 如果为 0,响应 SHOULD 被视为立即过期;客户端 MAY 在每次需要结果时重新获取。
- 如果为正数,客户端 SHOULD 在收到响应后的这么多毫秒内将结果视为新鲜。
表示缓存响应的预期范围,类似于 HTTP Cache-Control: public 与 Cache-Control: private。
“public”:任何客户端或中介(例如共享网关、代理)MAY 缓存响应并将其提供给任何用户。“private”:只有发出请求用户的客户端 MAY 缓存响应。共享缓存(例如多租户网关)MUST NOT 将缓存副本提供给其他用户。
Resource
icons?: Icon[];
name: string;
title?: string;
uri: string;
description?: string;
mimeType?: string;
annotations?: Annotations;
size?: number;
_meta?: MetaObject;
}
服务器能够读取的已知资源。
客户端可在用户界面中显示的一组带尺寸图标,可选。
支持渲染图标的客户端 MUST 至少支持以下 MIME 类型:
image/png- PNG 图像(安全,通用兼容)image/jpeg(以及image/jpg)- JPEG 图像(安全,通用兼容)
支持渲染图标的客户端 SHOULD 也支持:
image/svg+xml- SVG 图像(可缩放但需要安全预防措施)image/webp- WebP 图像(现代、高效格式)
用于程序化或逻辑用途,但在以往规范或回退场景中(如果 title 不存在)也用作显示名称。
用于 UI 和最终用户上下文——优化为人类可读且易于理解,即使读者不熟悉特定领域术语。
如果未提供,应使用 name 进行显示(但对于 Tool,如果存在 annotations.title,则应优先于 name 使用)。
此资源的 URI。
对此资源所表示内容的描述。
客户端可使用此信息改进 LLM 对可用资源的理解。可将其视为给模型的“提示”。
此资源的 MIME 类型(如果已知)。
供客户端使用的可选注释。
原始资源内容的大小(以字节为单位,即 Base64 编码或任何分词之前),如果已知。
Host 可使用此信息显示文件大小并估算上下文窗口使用量。
resources/read
ReadResourceRequest
jsonrpc: “2.0”;
id: RequestId;
method: “resources/read”;
params: ReadResourceRequestParams;
}
客户端发送给服务器,用于读取特定资源 URI。
示例:读取资源请求
{
“jsonrpc”: “2.0”,
“id”: “read-resource-example”,
“method”: “resources/read”,
“params”: {
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
},
“uri”: “file:///project/src/main.rs”
}
} ReadResourceRequestParams
_meta: RequestMetaObject;
inputResponses?: InputResponses;
requestState?: string;
uri: string;
}
resources/read 请求的参数。
资源的 URI。URI 可以使用任何协议;如何解释由服务器决定。
ReadResourceResultResponse
jsonrpc: “2.0”;
id: RequestId;
result: InputRequiredResult | ReadResourceResult;
}
服务器针对 resources/read 请求返回的成功响应。
ReadResourceResult
_meta?: MetaObject;
resultType: string;
ttlMs: number;
cacheScope: “public” | “private”;
contents: (TextResourceContents | BlobResourceContents)[];
[key: string]: unknown;
}
服务器针对 resources/read 请求返回的结果。
表示结果的类型,使客户端能够确定如何解析结果对象。
实现此协议版本的服务器 MUST 包含此字段。为了向后兼容,当客户端从实现较早协议版本的服务器收到结果(其中不包含 resultType)时,客户端 MUST 将缺失字段视为 “complete”。
服务器提供的提示,表示客户端在重新获取前 MAY 缓存此响应多长时间(以毫秒为单位)。语义类似于 HTTP Cache-Control max-age。
- 如果为 0,响应 SHOULD 被视为立即过期;客户端 MAY 在每次需要结果时重新获取。
- 如果为正数,客户端 SHOULD 在收到响应后的这么多毫秒内将结果视为新鲜。
表示缓存响应的预期范围,类似于 HTTP Cache-Control: public 与 Cache-Control: private。
“public”:任何客户端或中介(例如共享网关、代理)MAY 缓存响应并将其提供给任何用户。“private”:只有发出请求用户的客户端 MAY 缓存响应。共享缓存(例如多租户网关)MUST NOT 将缓存副本提供给其他用户。
resources/templates/list
ListResourceTemplatesRequest
jsonrpc: “2.0”;
id: RequestId;
params: PaginatedRequestParams;
method: “resources/templates/list”;
}
客户端发送,用于请求服务器拥有的资源模板列表。
示例:列出资源模板请求
{
“jsonrpc”: “2.0”,
“id”: “list-resource-templates-example”,
“method”: “resources/templates/list”,
“params”: {
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
}
}
} ListResourceTemplatesResultResponse
jsonrpc: “2.0”;
id: RequestId;
result: ListResourceTemplatesResult;
}
服务器针对 resources/templates/list 请求返回的成功响应。
示例:列出资源模板结果响应
{
“jsonrpc”: “2.0”,
“id”: “list-resource-templates-example”,
“result”: {
“resultType”: “complete”,
“resourceTemplates”: [
{
“uriTemplate”: “file:///{path}”,
“name”: “Project Files”,
“title”: “Project Files”,
“description”: “Access files in the project directory”,
“mimeType”: “application/octet-stream”,
“icons”: [
{
“src”: “https://example.com/folder-icon.png”,
“mimeType”: “image/png”,
“sizes”: [“48x48”]
}
]
}
],
“ttlMs”: 3600000,
“cacheScope”: “public”
}
} ListResourceTemplatesResult
_meta?: MetaObject;
resultType: string;
nextCursor?: string;
ttlMs: number;
cacheScope: “public” | “private”;
resourceTemplates: ResourceTemplate[];
[key: string]: unknown;
}
服务器针对 resources/templates/list 请求返回的结果。
示例:带游标和 TTL 的资源模板列表
{
“resultType”: “complete”,
“resourceTemplates”: [
{
“uriTemplate”: “file:///{path}”,
“name”: “Project Files”,
“title”: ”📁 Project Files”,
“description”: “Access files in the project directory”,
“mimeType”: “application/octet-stream”,
“icons”: [
{
“src”: “https://example.com/folder-icon.png”,
“mimeType”: “image/png”,
“sizes”: [“48x48”]
}
]
}
],
“nextCursor”: “next-page-cursor”,
“ttlMs”: 3600000,
“cacheScope”: “public”
} 表示结果的类型,使客户端能够确定如何解析结果对象。
实现此协议版本的服务器 MUST 包含此字段。为了向后兼容,当客户端从实现较早协议版本的服务器收到结果(其中不包含 resultType)时,客户端 MUST 将缺失字段视为 “complete”。
表示最后一个返回结果之后分页位置的不透明令牌。如果存在,可能还有更多结果可用。
服务器提供的提示,表示客户端在重新获取前 MAY 缓存此响应多长时间(以毫秒为单位)。语义类似于 HTTP Cache-Control max-age。
- 如果为 0,响应 SHOULD 被视为立即过期;客户端 MAY 在每次需要结果时重新获取。
- 如果为正数,客户端 SHOULD 在收到响应后的这么多毫秒内将结果视为新鲜。
表示缓存响应的预期范围,类似于 HTTP Cache-Control: public 与 Cache-Control: private。
“public”:任何客户端或中介(例如共享网关、代理)MAY 缓存响应并将其提供给任何用户。“private”:只有发出请求用户的客户端 MAY 缓存响应。共享缓存(例如多租户网关)MUST NOT 将缓存副本提供给其他用户。
ResourceTemplate
icons?: Icon[];
name: string;
title?: string;
uriTemplate: string;
description?: string;
mimeType?: string;
annotations?: Annotations;
_meta?: MetaObject;
}
服务器上可用资源的模板描述。
客户端可在用户界面中显示的一组带尺寸图标,可选。
支持渲染图标的客户端 MUST 至少支持以下 MIME 类型:
image/png- PNG 图像(安全,通用兼容)image/jpeg(以及image/jpg)- JPEG 图像(安全,通用兼容)
支持渲染图标的客户端 SHOULD 也支持:
image/svg+xml- SVG 图像(可缩放但需要安全预防措施)image/webp- WebP 图像(现代、高效格式)
用于程序化或逻辑用途,但在以往规范或回退场景中(如果 title 不存在)也用作显示名称。
用于 UI 和最终用户上下文——优化为人类可读且易于理解,即使读者不熟悉特定领域术语。
如果未提供,应使用 name 进行显示(但对于 Tool,如果存在 annotations.title,则应优先于 name 使用)。
可用于构造资源 URI 的 URI 模板(依据 RFC 6570)。
对此模板用途的描述。
客户端可使用此信息改进 LLM 对可用资源的理解。可将其视为给模型的“提示”。
匹配此模板的所有资源的 MIME 类型。仅当所有匹配此模板的资源具有相同类型时才应包含。
供客户端使用的可选注释。
roots/list
ListRootsRequest
服务器发送,用于向客户端请求根 URI 列表。根目录允许服务器请求可操作的特定目录或文件。根目录的常见示例是提供一组服务器应操作的仓库或目录。
当服务器需要了解文件系统结构,或访问客户端有权限读取的特定位置时,通常使用此请求。
自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
ListRootsResult
客户端针对 roots/list 请求返回的结果。此结果包含一个 Root 对象数组,每个对象表示服务器可操作的根目录或文件。
示例:多个根目录
{
“roots”: [
{
“uri”: “file:///home/user/repos/frontend”,
“name”: “Frontend Repository”
},
{
“uri”: “file:///home/user/repos/backend”,
“name”: “Backend Repository”
}
]
} 自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
Root
表示服务器可操作的根目录或文件。
自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
标识根目录的 URI。目前它必须以 file:// 开头。未来协议版本可能会放宽此限制,以允许其他 URI 方案。
根目录的可选名称。可用于为根目录提供人类可读标识符,这对显示用途或在应用程序其他部分引用根目录可能有用。
sampling/createMessage
CreateMessageRequest
method: “sampling/createMessage”;
params: CreateMessageRequestParams;
}
服务器通过客户端对 LLM 进行采样的请求。客户端可完全自行决定选择哪个模型。客户端还应在开始采样前通知用户,使其能够检查请求(人在环路中)并决定是否批准。
示例:采样请求
{
“method”: “sampling/createMessage”,
“params”: {
“messages”: [
{
“role”: “user”,
“content”: {
“type”: “text”,
“text”: “What is the capital of France?”
}
}
],
“modelPreferences”: {
“hints”: [
{
“name”: “claude-3-sonnet”
}
],
“intelligencePriority”: 0.8,
“speedPriority”: 0.5
},
“systemPrompt”: “You are a helpful assistant.”,
“maxTokens”: 100
}
} 自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
CreateMessageRequestParams
messages: SamplingMessage[];
modelPreferences?: ModelPreferences;
systemPrompt?: string;
includeContext?: “none” | “thisServer” | “allServers”;
temperature?: number;
maxTokens: number;
stopSequences?: string[];
metadata?: JSONObject;
tools?: Tool[];
toolChoice?: ToolChoice;
}
sampling/createMessage 请求的参数。
示例:基础请求
{
“messages”: [
{
“role”: “user”,
“content”: {
“type”: “text”,
“text”: “What is the capital of France?”
}
}
],
“modelPreferences”: {
“hints”: [
{
“name”: “claude-3-sonnet”
}
],
“intelligencePriority”: 0.8,
“speedPriority”: 0.5
},
“systemPrompt”: “You are a helpful assistant.”,
“maxTokens”: 100
} 示例:带工具的请求
{
“messages”: [
{
“role”: “user”,
“content”: {
“type”: “text”,
“text”: “What’s the weather like in Paris and London?”
}
}
],
“tools”: [
{
“name”: “get_weather”,
“description”: “Get current weather for a city”,
“inputSchema”: {
“type”: “object”,
“properties”: {
“city”: {
“type”: “string”,
“description”: “City name”
}
},
“required”: [“city”]
}
}
],
“toolChoice”: {
“mode”: “auto”
},
“maxTokens”: 1000
} 示例:带工具结果的后续请求
{
“messages”: [
{
“role”: “user”,
“content”: {
“type”: “text”,
“text”: “What’s the weather like in Paris and London?”
}
},
{
“role”: “assistant”,
“content”: [
{
“type”: “tool_use”,
“id”: “call_abc123”,
“name”: “get_weather”,
“input”: { “city”: “Paris” }
},
{
“type”: “tool_use”,
“id”: “call_def456”,
“name”: “get_weather”,
“input”: { “city”: “London” }
}
]
},
{
“role”: “user”,
“content”: [
{
“type”: “tool_result”,
“toolUseId”: “call_abc123”,
“content”: [
{
“type”: “text”,
“text”: “Weather in Paris: 18°C, partly cloudy”
}
]
},
{
“type”: “tool_result”,
“toolUseId”: “call_def456”,
“content”: [
{
“type”: “text”,
“text”: “Weather in London: 15°C, rainy”
}
]
}
]
}
],
“tools”: [
{
“name”: “get_weather”,
“description”: “Get current weather for a city”,
“inputSchema”: {
“type”: “object”,
“properties”: {
“city”: { “type”: “string” }
},
“required”: [“city”]
}
}
],
“maxTokens”: 1000
} 自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
服务器对模型选择的偏好。客户端 MAY 忽略这些偏好。
服务器希望用于采样的可选系统提示。客户端 MAY 修改或省略此提示。
请求包含来自一个或多个 MCP 服务器(包括调用方)的上下文,并将其附加到提示中。客户端 MAY 忽略此请求。
默认值为 “none”。“thisServer” 和 “allServers” 值已弃用(SEP-2596):服务器 SHOULD 省略此字段或使用 “none”,并且 SHOULD 仅在客户端声明 ClientCapabilities.sampling.context 时使用已弃用的值。
”thisServer” 和 “allServers” 值自协议版本 2025-11-25(SEP-2596)起弃用,并且最晚会随采样功能本身(SEP-2577)一起移除。请省略此字段或使用 “none”。
请求采样的最大 token 数(用于防止补全失控)。
客户端 MAY 选择采样少于请求上限的 token。
传递给 LLM 提供商的可选元数据。此元数据的格式由提供商决定。
模型在生成期间可使用的工具。如果提供了此字段但未声明 ClientCapabilities.sampling.tools,客户端 MUST 返回错误。
控制模型如何使用工具。如果提供了此字段但未声明 ClientCapabilities.sampling.tools,客户端 MUST 返回错误。默认值为 { mode: “auto” }。
CreateMessageResult
model: string;
stopReason?: string;
role: Role;
content: SamplingMessageContentBlock | SamplingMessageContentBlock[];
_meta?: MetaObject;
}
客户端针对 sampling/createMessage 请求返回的结果。客户端应在返回采样消息前通知用户,使其能够检查响应(人在环路中)并决定是否允许服务器看到它。
示例:文本响应
{
“role”: “assistant”,
“content”: {
“type”: “text”,
“text”: “The capital of France is Paris.”
},
“model”: “claude-3-sonnet-20240307”,
“stopReason”: “endTurn”
} 示例:工具使用响应
{
“role”: “assistant”,
“content”: [
{
“type”: “tool_use”,
“id”: “call_abc123”,
“name”: “get_weather”,
“input”: {
“city”: “Paris”
}
},
{
“type”: “tool_use”,
“id”: “call_def456”,
“name”: “get_weather”,
“input”: {
“city”: “London”
}
}
],
“model”: “claude-3-sonnet-20240307”,
“stopReason”: “toolUse”
} 示例:工具使用后的最终响应
{
“role”: “assistant”,
“content”: {
“type”: “text”,
“text”: “Based on the current weather data:\n\n- **Paris**: 18°C and partly cloudy - quite pleasant!\n- **London**: 15°C and rainy - you’ll want an umbrella.\n\nParis has slightly warmer and drier conditions today.”
},
“model”: “claude-3-sonnet-20240307”,
“stopReason”: “endTurn”
} 自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
生成该消息的模型名称。
采样停止的原因(如果已知)。
标准值:
“endTurn”:助手回合自然结束“stopSequence”:遇到停止序列“maxTokens”:达到最大 token 限制“toolUse”:模型希望使用一个或多个工具
此字段是开放字符串,用于允许提供商特定的停止原因。
ModelHint
用于模型选择的提示。
此处未声明的键目前在规范中未指定,由客户端解释。
自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
模型名称提示。
客户端 SHOULD 将其视为模型名称的子字符串;例如:
claude-3-5-sonnet应匹配claude-3-5-sonnet-20241022sonnet应匹配claude-3-5-sonnet-20241022、claude-3-sonnet-20240229等。claude应匹配任何 Claude 模型
只要用途相近,客户端 MAY 也可将该字符串映射到其他提供商的模型名称或不同模型系列;例如:
gemini-1.5-flash可匹配claude-3-haiku-20240307
ModelPreferences
hints?: ModelHint[];
costPriority?: number;
speedPriority?: number;
intelligencePriority?: number;
}
服务器在采样期间向客户端请求的模型选择偏好。
由于 LLM 可能在多个维度上存在差异,选择“最佳”模型很少是直接明了的。不同模型擅长不同方面——有些更快但能力较弱,有些能力更强但更昂贵,等等。此接口允许服务器表达多个维度上的优先级,帮助客户端为其用例做出适当选择。
这些偏好始终仅供参考。客户端 MAY 忽略它们。客户端也自行决定如何解释这些偏好,以及如何将其与其他考虑因素进行权衡。
示例:带提示和优先级
{
“hints”: [
{ “name”: “claude-3-sonnet” },
{ “name”: “claude” }
],
“costPriority”: 0.3,
“speedPriority”: 0.8,
“intelligencePriority”: 0.5
} 自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
用于模型选择的可选提示。
如果指定了多个提示,客户端 MUST 按顺序评估它们(采用第一个匹配项)。
客户端 SHOULD 优先考虑这些提示而非数值优先级,但 MAY 仍使用优先级从模糊匹配中进行选择。
选择模型时对成本的优先程度。值为 0 表示成本不重要,值为 1 表示成本是最重要的因素。
选择模型时对采样速度(延迟)的优先程度。值为 0 表示速度不重要,值为 1 表示速度是最重要的因素。
选择模型时对智能和能力的优先程度。值为 0 表示智能不重要,值为 1 表示智能是最重要的因素。
SamplingMessage
role: Role;
content: SamplingMessageContentBlock | SamplingMessageContentBlock[];
_meta?: MetaObject;
}
描述发送给 LLM API 或从 LLM API 接收的消息。
示例:多个内容块
{
“role”: “user”,
“content”: [
{
“type”: “tool_result”,
“toolUseId”: “call_123”,
“content”: [{ “type”: “text”, “text”: “Result 1” }]
},
{
“type”: “tool_result”,
“toolUseId”: “call_456”,
“content”: [{ “type”: “text”, “text”: “Result 2” }]
}
]
} 自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
SamplingMessageContentBlock
| TextContent
| ImageContent
| AudioContent
| ToolUseContent
| ToolResultContent
自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
ToolChoice
控制采样请求的工具选择行为。
自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
控制模型使用工具的能力:
“auto”:模型决定是否使用工具(默认)“required”:模型 MUST 在完成前使用至少一个工具“none”:模型 MUST NOT 使用任何工具
ToolResultContent
type: “tool_result”;
toolUseId: string;
content: ContentBlock[];
structuredContent?: unknown;
isError?: boolean;
_meta?: MetaObject;
}
工具使用的结果,由用户提供回助手。
示例:`get_weather` 工具结果
{
“type”: “tool_result”,
“toolUseId”: “call_abc123”,
“content”: [
{
“type”: “text”,
“text”: “Weather in Paris: 18°C, partly cloudy”
}
]
} 自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
此结果对应的工具使用 ID。
这 MUST 与先前 ToolUseContent 中的 ID 匹配。
工具使用的非结构化结果内容。
其格式与 CallToolResult.content 相同,可包含文本、图像、音频、资源链接和嵌入资源。
可选的结构化结果值。
可以是任何 JSON 值(对象、数组、字符串、数字、布尔值或 null)。如果工具定义了 Tool.outputSchema,则此值 SHOULD 符合该 schema。
工具使用是否产生错误。
如果为 true,内容通常描述发生的错误。 默认值:false
关于工具结果的可选元数据。客户端在后续采样请求中包含工具结果时 SHOULD 保留此字段,以启用缓存优化。
ToolUseContent
type: “tool_use”;
id: string;
name: string;
input: { [key: string]: unknown };
_meta?: MetaObject;
}
助手发出的调用工具请求。
示例:`get_weather` 工具使用
{
“type”: “tool_use”,
“id”: “call_abc123”,
“name”: “get_weather”,
“input”: {
“city”: “Paris”
}
} 自协议版本 2026-07-28(SEP-2577)起弃用。将在规范中至少保留十二个月;请参见已弃用功能注册表。
此工具使用的唯一标识符。
此 ID 用于将工具结果与对应的工具使用进行匹配。
要调用的工具名称。
传递给工具的参数,符合该工具的输入 schema。
关于工具使用的可选元数据。客户端在后续采样请求中包含工具使用时 SHOULD 保留此字段,以启用缓存优化。
server/discover
DiscoverRequest
jsonrpc: “2.0”;
id: RequestId;
method: “server/discover”;
params: RequestParams;
}
客户端请求服务器公布其支持的协议版本、能力和其他元数据的请求。服务器 MUST 实现 server/discover。客户端 MAY 调用它,但不是必需的——版本协商也可以通过每个请求的 _meta 内联发生。
DiscoverResult
_meta?: MetaObject;
resultType: string;
supportedVersions: string[];
capabilities: ServerCapabilities;
serverInfo: Implementation;
instructions?: string;
ttlMs: number;
cacheScope: “public” | “private”;
[key: string]: unknown;
}
服务器针对 server/discover 请求返回的结果。
示例:服务器能力发现
{
“resultType”: “complete”,
“supportedVersions”: [“2026-07-28”],
“capabilities”: {
“tools”: {},
“resources”: {}
},
“serverInfo”: {
“name”: “ExampleServer”,
“version”: “1.0.0”
},
“instructions”: “This server provides weather and resource utilities. Prefer `get_weather` for forecast lookups.”,
“ttlMs”: 3600000,
“cacheScope”: “public”
} 表示结果的类型,使客户端能够确定如何解析结果对象。
实现此协议版本的服务器 MUST 包含此字段。为了向后兼容,当客户端从实现较早协议版本的服务器收到结果(其中不包含 resultType)时,客户端 MUST 将缺失字段视为 “complete”。
此服务器支持的 MCP 协议版本。客户端应从此列表中选择一个版本用于后续请求。
服务器的能力。
关于服务器软件实现的信息。
描述服务器及其功能的自然语言指导。
客户端可使用此信息改进 LLM 对可用工具的理解(例如将其包含在系统提示中)。它应专注于帮助模型有效使用服务器的信息,并且不应重复工具描述中已有的信息。
服务器提供的提示,表示客户端在重新获取前 MAY 缓存此响应多长时间(以毫秒为单位)。语义类似于 HTTP Cache-Control max-age。
- 如果为 0,响应 SHOULD 被视为立即过期;客户端 MAY 在每次需要结果时重新获取。
- 如果为正数,客户端 SHOULD 在收到响应后的这么多毫秒内将结果视为新鲜。
表示缓存响应的预期范围,类似于 HTTP Cache-Control: public 与 Cache-Control: private。
“public”:任何客户端或中介(例如共享网关、代理)MAY 缓存响应并将其提供给任何用户。“private”:只有发出请求用户的客户端 MAY 缓存响应。共享缓存(例如多租户网关)MUST NOT 将缓存副本提供给其他用户。
ClientCapabilities
experimental?: { [key: string]: JSONObject };
roots?: {};
sampling?: { context?: JSONObject; tools?: JSONObject };
elicitation?: { form?: JSONObject; url?: JSONObject };
extensions?: { [key: string]: JSONObject };
}
客户端可能支持的能力。已知能力在此 schema 中定义,但这不是封闭集合:任何客户端都可以定义自己的附加能力。
客户端支持的实验性非标准能力。
如果客户端支持列出根目录,则存在。
如果客户端支持从 LLM 采样,则存在。
客户端是否支持通过
includeContext参数包含上下文。如果未声明,服务器 SHOULD 只使用includeContext: “none”(或省略它)。客户端是否支持通过
tools和toolChoice参数使用工具。
如果客户端支持来自服务器的引出,则存在。
客户端支持的可选 MCP 扩展。键是扩展标识符(例如 “io.modelcontextprotocol/oauth-client-credentials”),值是每个扩展的设置对象。空对象表示支持但没有设置。
键 MUST 遵循 _meta 键命名规则,并带有强制前缀。
Implementation
icons?: Icon[];
name: string;
title?: string;
version: string;
description?: string;
websiteUrl?: string;
}
描述 MCP 实现。
客户端可在用户界面中显示的一组带尺寸图标,可选。
支持渲染图标的客户端 MUST 至少支持以下 MIME 类型:
image/png- PNG 图像(安全,通用兼容)image/jpeg(以及image/jpg)- JPEG 图像(安全,通用兼容)
支持渲染图标的客户端 SHOULD 也支持:
image/svg+xml- SVG 图像(可缩放但需要安全预防措施)image/webp- WebP 图像(现代、高效格式)
用于程序化或逻辑用途,但在以往规范或回退场景中(如果 title 不存在)也用作显示名称。
用于 UI 和最终用户上下文——优化为人类可读且易于理解,即使读者不熟悉特定领域术语。
如果未提供,应使用 name 进行显示(但对于 Tool,如果存在 annotations.title,则应优先于 name 使用)。
此实现的版本。
对此实现功能的人类可读可选描述。
客户端或服务器可使用此信息提供有关其用途和能力的上下文。例如,服务器可描述其提供的资源或工具类型,而客户端可描述其预期用例。
此实现网站的可选 URL。
ServerCapabilities
experimental?: { [key: string]: JSONObject };
logging?: JSONObject;
completions?: JSONObject;
prompts?: { listChanged?: boolean };
resources?: { subscribe?: boolean; listChanged?: boolean };
tools?: { listChanged?: boolean };
extensions?: { [key: string]: JSONObject };
}
服务器可能支持的能力。已知能力在此 schema 中定义,但这不是封闭集合:任何服务器都可以定义自己的附加能力。
服务器支持的实验性非标准能力。
如果服务器支持向客户端发送日志消息,则存在。
如果服务器支持参数自动补全建议,则存在。
如果服务器提供任何提示模板,则存在。
OptionallistChanged?: boolean此服务器是否支持提示列表更改通知。
如果服务器提供任何可读取资源,则存在。
Optionalsubscribe?: boolean此服务器是否支持订阅资源更新。
OptionallistChanged?: boolean此服务器是否支持资源列表更改通知。
如果服务器提供任何可调用工具,则存在。
OptionallistChanged?: boolean此服务器是否支持工具列表更改通知。
服务器支持的可选 MCP 扩展。键是扩展标识符(例如 “io.modelcontextprotocol/tasks”),值是每个扩展的设置对象。空对象表示支持但没有设置。
键 MUST 遵循 _meta 键命名规则,并带有强制前缀。
subscriptions/listen
SubscriptionsListenRequest
jsonrpc: “2.0”;
id: RequestId;
method: “subscriptions/listen”;
params: SubscriptionsListenRequestParams;
}
客户端发送,用于打开一个长生命周期通道,以接收特定请求上下文之外的通知。取代之前的 HTTP GET 端点,并确保 HTTP 与 STDIO 之间行为一致。
示例:监听工具和资源列表更改
{
“jsonrpc”: “2.0”,
“id”: “listen-1”,
“method”: “subscriptions/listen”,
“params”: {
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
},
“notifications”: {
“toolsListChanged”: true,
“resourceSubscriptions”: [“file:///project/config.json”]
}
}
} SubscriptionsListenRequestParams
_meta: RequestMetaObject;
notifications: SubscriptionFilter;
}
subscriptions/listen 请求的参数。
客户端在此流上选择接收的通知。服务器 MUST NOT 发送客户端未明确请求的通知类型。
SubscriptionFilter
toolsListChanged?: boolean;
promptsListChanged?: boolean;
resourcesListChanged?: boolean;
resourceSubscriptions?: string[];
}
客户端可在 subscriptions/listen 请求中选择接收的通知类型集合。
每种通知类型都是选择接收;服务器 MUST NOT 发送客户端未在此明确请求的通知类型。
如果为 true,则接收 notifications/tools/list_changed。
如果为 true,则接收 notifications/prompts/list_changed。
如果为 true,则接收 notifications/resources/list_changed。
为这些资源 URI 订阅 notifications/resources/updated。取代以前的 resources/subscribe RPC。
tools/call
CallToolRequest
jsonrpc: “2.0”;
id: RequestId;
method: “tools/call”;
params: CallToolRequestParams;
}
客户端用于调用服务器提供的工具。
示例:调用工具请求
{
“jsonrpc”: “2.0”,
“id”: “call-tool-example”,
“method”: “tools/call”,
“params”: {
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
},
“name”: “get_weather”,
“arguments”: {
“location”: “New York”
}
}
} CallToolRequestParams
_meta: RequestMetaObject;
inputResponses?: InputResponses;
requestState?: string;
name: string;
arguments?: { [key: string]: unknown };
}
tools/call 请求的参数。
示例:`get_weather` 工具调用参数
{
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
},
“name”: “get_weather”,
“arguments”: {
“location”: “New York”
}
} 示例:带进度令牌的工具调用参数
{
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {},
“progressToken”: “oivaizmir”
},
“name”: “build_simulation”,
“arguments”: {
“city”: “Micropolis”
}
} 工具的名称。
用于工具调用的参数。
CallToolResultResponse
jsonrpc: “2.0”;
id: RequestId;
result: InputRequiredResult | CallToolResult;
}
服务器针对 tools/call 请求返回的成功响应。
CallToolResult
_meta?: MetaObject;
resultType: string;
content: ContentBlock[];
structuredContent?: unknown;
isError?: boolean;
[key: string]: unknown;
}
服务器针对 tools/call 请求返回的结果。
示例:带非结构化文本的结果
{
“resultType”: “complete”,
“content”: [
{
“type”: “text”,
“text”: “Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy”
}
],
“isError”: false
} 表示结果的类型,使客户端能够确定如何解析结果对象。
实现此协议版本的服务器 MUST 包含此字段。为了向后兼容,当客户端从实现较早协议版本的服务器收到结果(其中不包含 resultType)时,客户端 MUST 将缺失字段视为 “complete”。
表示工具调用非结构化结果的内容对象列表。
表示工具调用结构化结果的可选 JSON 值。
可以是任何 JSON 值(对象、数组、字符串、数字、布尔值或 null),如果定义了工具的 outputSchema,则该值符合它。
工具调用是否以错误结束。
如果未设置,则假定为 false(调用成功)。
任何源自工具的错误 SHOULD 在结果对象内部报告,并将 isError 设置为 true,不要作为 MCP 协议级错误响应报告。否则,LLM 将无法看到发生了错误并自行纠正。
但是,任何查找工具时的错误、表示服务器不支持工具调用的错误,或任何其他异常情况,都应作为 MCP 错误响应报告。
tools/list
ListToolsRequest
jsonrpc: “2.0”;
id: RequestId;
params: PaginatedRequestParams;
method: “tools/list”;
}
客户端发送,用于请求服务器拥有的工具列表。
示例:列出工具请求
{
“jsonrpc”: “2.0”,
“id”: “list-tools-example”,
“method”: “tools/list”,
“params”: {
“_meta”: {
“io.modelcontextprotocol/protocolVersion”: “2026-07-28”,
“io.modelcontextprotocol/clientInfo”: {
“name”: “ExampleClient”,
“version”: “1.0.0”
},
“io.modelcontextprotocol/clientCapabilities”: {}
}
}
} ListToolsResultResponse
服务器针对 tools/list 请求返回的成功响应。
示例:列出工具结果响应
{
“jsonrpc”: “2.0”,
“id”: “list-tools-example”,
“result”: {
“resultType”: “complete”,
“tools”: [
{
“name”: “get_weather”,
“title”: “Weather Information Provider”,
“description”: “Get current weather information for a location”,
“inputSchema”: {
“type”: “object”,
“properties”: {
“location”: {
“type”: “string”,
“description”: “City name or zip code”
}
},
“required”: [“location”]
},
“icons”: [
{
“src”: “https://example.com/weather-icon.png”,
“mimeType”: “image/png”,
“sizes”: [“48x48”]
}
]
}
],
“nextCursor”: “next-page-cursor”,
“ttlMs”: 3600000,
“cacheScope”: “public”
}
} ListToolsResult
_meta?: MetaObject;
resultType: string;
nextCursor?: string;
ttlMs: number;
cacheScope: “public” | “private”;
tools: Tool[];
[key: string]: unknown;
}
服务器针对 tools/list 请求返回的结果。
示例:带游标和 TTL 的工具列表
{
“resultType”: “complete”,
“tools”: [
{
“name”: “get_weather”,
“title”: “Weather Information Provider”,
“description”: “Get current weather information for a location”,
“inputSchema”: {
“type”: “object”,
“properties”: {
“location”: {
“type”: “string”,
“description”: “City name or zip code”
}
},
“required”: [“location”]
},
“icons”: [
{
“src”: “https://example.com/weather-icon.png”,
“mimeType”: “image/png”,
“sizes”: [“48x48”]
}
]
}
],
“nextCursor”: “next-page-cursor”,
“ttlMs”: 300000,
“cacheScope”: “public”
} 表示结果的类型,使客户端能够确定如何解析结果对象。
实现此协议版本的服务器 MUST 包含此字段。为了向后兼容,当客户端从实现较早协议版本的服务器收到结果(其中不包含 resultType)时,客户端 MUST 将缺失字段视为 “complete”。
表示最后一个返回结果之后分页位置的不透明令牌。如果存在,可能还有更多结果可用。
服务器提供的提示,表示客户端在重新获取前 MAY 缓存此响应多长时间(以毫秒为单位)。语义类似于 HTTP Cache-Control max-age。
- 如果为 0,响应 SHOULD 被视为立即过期;客户端 MAY 在每次需要结果时重新获取。
- 如果为正数,客户端 SHOULD 在收到响应后的这么多毫秒内将结果视为新鲜。
表示缓存响应的预期范围,类似于 HTTP Cache-Control: public 与 Cache-Control: private。
“public”:任何客户端或中介(例如共享网关、代理)MAY 缓存响应并将其提供给任何用户。“private”:只有发出请求用户的客户端 MAY 缓存响应。共享缓存(例如多租户网关)MUST NOT 将缓存副本提供给其他用户。
Tool
icons?: Icon[];
name: string;
title?: string;
description?: string;
inputSchema: { $schema?: string; type: “object”; [key: string]: unknown };
outputSchema?: { $schema?: string; [key: string]: unknown };
annotations?: ToolAnnotations;
_meta?: MetaObject;
}
客户端可调用工具的定义。
示例:带默认 2020-12 输入 schema
{
“name”: “calculate_sum”,
“description”: “Add two numbers”,
“inputSchema”: {
“type”: “object”,
“properties”: {
“a”: { “type”: “number” },
“b”: { “type”: “number” }
},
“required”: [“a”, “b”]
}
} 示例:带显式 draft-07 输入 schema
{
“name”: “calculate_sum”,
“description”: “Add two numbers”,
“inputSchema”: {
“$schema”: “http://json-schema.org/draft-07/schema#”,
“type”: “object”,
“properties”: {
“a”: { “type”: “number” },
“b”: { “type”: “number” }
},
“required”: [“a”, “b”]
}
} 示例:无参数
{
“name”: “get_current_time”,
“description”: “Returns the current server time”,
“inputSchema”: {
“type”: “object”,
“additionalProperties”: false
}
} 示例:带结构化内容输出 schema
{
“name”: “get_weather_data”,
“title”: “Weather Data Retriever”,
“description”: “Get current weather data for a location”,
“inputSchema”: {
“type”: “object”,
“properties”: {
“location”: {
“type”: “string”,
“description”: “City name or zip code”
}
},
“required”: [“location”]
},
“outputSchema”: {
“type”: “object”,
“properties”: {
“temperature”: {
“type”: “number”,
“description”: “Temperature in celsius”
},
“conditions”: {
“type”: “string”,
“description”: “Weather conditions description”
},
“humidity”: {
“type”: “number”,
“description”: “Humidity percentage”
}
},
“required”: [“temperature”, “conditions”, “humidity”]
}
} 客户端可在用户界面中显示的一组带尺寸图标,可选。
支持渲染图标的客户端 MUST 至少支持以下 MIME 类型:
image/png- PNG 图像(安全,通用兼容)image/jpeg(以及image/jpg)- JPEG 图像(安全,通用兼容)
支持渲染图标的客户端 SHOULD 也支持:
image/svg+xml- SVG 图像(可缩放但需要安全预防措施)image/webp- WebP 图像(现代、高效格式)
用于程序化或逻辑用途,但在以往规范或回退场景中(如果 title 不存在)也用作显示名称。
用于 UI 和最终用户上下文——优化为人类可读且易于理解,即使读者不熟悉特定领域术语。
如果未提供,应使用 name 进行显示(但对于 Tool,如果存在 annotations.title,则应优先于 name 使用)。
工具的人类可读描述。
客户端可使用此信息改进 LLM 对可用工具的理解。可将其视为给模型的“提示”。
定义工具预期参数的 JSON Schema 对象。
工具参数始终是 JSON 对象,因此根级别需要 type: “object”。除此之外,任何 JSON Schema 2020-12 关键字都可以与 type 一起出现——包括组合关键字(oneOf、anyOf、allOf、not)、条件关键字(if/then/else)、引用关键字($ref、$defs、$anchor),以及任何其他标准验证或注释关键字。
当未提供显式 $schema 时,默认为 JSON Schema 2020-12。
可选的 JSON Schema 对象,定义在 CallToolResult 的 structuredContent 字段中返回的工具输出结构。它可以是任何有效的 JSON Schema 2020-12。
当未提供显式 $schema 时,默认为 JSON Schema 2020-12。
可选的附加工具信息。
显示名称优先级顺序为:title、annotations.title,然后是 name。
ToolAnnotations
title?: string;
readOnlyHint?: boolean;
destructiveHint?: boolean;
idempotentHint?: boolean;
openWorldHint?: boolean;
}
向客户端描述 Tool 的附加属性。
注意:ToolAnnotations 中的所有属性都是提示。它们不保证能忠实描述工具行为(包括 title 这类描述性属性)。
客户端绝不应根据从不受信任服务器收到的 ToolAnnotations 做出工具使用决策。
工具的人类可读标题。
如果为 true,该工具不会修改其环境。
默认值:false
如果为 true,该工具可能对其环境执行破坏性更新。如果为 false,该工具仅执行增量更新。
(仅当 readOnlyHint == false 时,此属性才有意义)
默认值:true
如果为 true,使用相同参数重复调用该工具不会对其环境产生额外影响。
(仅当 readOnlyHint == false 时,此属性才有意义)
默认值:false
如果为 true,此工具可能与外部实体的“开放世界”交互。如果为 false,工具的交互域是封闭的。例如,Web 搜索工具的世界是开放的,而内存工具的世界不是。
默认值:true
表示请求发生错误的响应。