概述
模型上下文协议由几个协同工作的关键组件组成:
- 基础协议:核心 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 不得在同一会话中之前被请求者使用过。
响应
响应作为请求的回复发送,包含操作的结果或错误。
结果响应
当操作成功完成时,发送结果响应。
{
jsonrpc: "2.0";
id: string | number;
result: {
[key: string]: unknown;
}
}- 结果响应必须包括与其对应的请求相同的 ID。
- 结果响应必须包括
result字段。 result可以遵循任何 JSON 对象结构。
错误响应
当操作失败或遇到错误时,发送错误响应。
{
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 的传输的实现应该遵循此规范,而使用标准输入输出传输的实现不应该遵循此规范,而应从环境中检索凭据。
此外,客户端和服务器可以协商自己的自定义身份验证和授权策略。
要进一步讨论和贡献 MCP 授权机制的演变,请加入我们的 GitHub 讨论 帮助塑造协议的未来!
Schema
协议的完整规范定义为 TypeScript schema。这是所有协议消息和结构的真实来源。
还有一个 JSON Schema,它是从 TypeScript 真实源自动生成的,用于各种自动化工具。
JSON Schema 使用
模型上下文协议在整个协议中使用 JSON Schema 进行验证。本节阐明了如何在 MCP 消息中使用 JSON Schema。
Schema 方言
MCP 支持具有以下规则的 JSON Schema:
- 默认方言:当 schema 不包括
$schema字段时,它默认为 JSON Schema 2020-12 - 显式方言:Schema 可以包括
$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字段的 schema 的 JSON Schema 2020-12 - 客户端和服务器必须根据其声明或默认方言验证 schema。它们必须通过返回适当的错误来优雅地处理不支持的语言,表明不支持该方言。
- 客户端和服务器应该记录它们支持的 schema 方言
Schema 验证
- Schema 必须根据其声明或默认方言有效
通用字段
_meta
MCP 保留 _meta 属性/参数,以允许客户端和服务器为其交互附加额外的元数据。
MCP 为协议级元数据保留某些键名,如下所述;实现不得对这些键的值做出假设。
此外,schema 中的定义可以为特定于目的的元数据保留特定名称,如这些定义中所声明的那样。
键名格式: 有效的 _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])开头和结尾。 - 可以在中间包含连字符(
-)、下划线(_)、点(.)和字母数字。
icons
icons 属性为服务器提供了一种标准化的方式来暴露其资源、工具、提示和实现的视觉标识符。图标通过提供视觉上下文和改进可用功能的可发现性来增强用户界面。
图标表示为 Icon 对象的数组,其中每个图标包括:
src:指向图标资源的 URI(必需)。这可以是:- 指向图像文件的 HTTP/HTTPS URL
- 具有 base64 编码图像数据的数据 URI
mimeType:如果服务器类型缺失或通用,则为可选的 MIME 类型sizes:可选的尺寸规范数组(例如,["48x48"]、可缩放格式如 SVG 的["any"],或多个尺寸的["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 中)的资源耗尽攻击具有弹性。
- 消费者可以设置图像和内容大小限制。
- 在没有凭据的情况下获取图标。不发送 cookies、
Authorization标头或客户端凭据。 - 验证图标 URI 与服务器同源。这最小化向第三方暴露数据或跟踪信息的风险。
- 在获取和渲染图标时要谨慎,因为有效负载可能包含可执行内容(例如,带有嵌入式 JavaScript或扩展功能的 SVG)。
- 消费者可以选择在渲染前禁止特定文件类型或以其他方式清理图标文件。
- 在渲染前验证 MIME 类型和文件内容。将 MIME 类型信息视为建议。通过魔术字节检测内容类型;在不匹配或未知类型时拒绝。
- 维护图像类型的严格允许列表。
用法:
图标可以附加到:
Implementation:MCP 服务器/客户端实现的视觉标识符Tool:工具功能的视觉表示Prompt:与提示模板一起显示的图标Resource:不同资源类型的视觉指示器
可以提供多个图标以支持不同的显示上下文和分辨率。客户端应根据其 UI 要求选择最合适的图标。