Model Context Protocol (MCP) 规范文档（2024-11-05版本）

Model Context Protocol (MCP) 规范文档（2024 11 05版本） Model Context Protocol (MCP) 规范文档（2024 11 05版本） Modified March 9, 2025 Code block JSON Copy { "jsonrpc": "2.0", "id": 1, "result": { "roots": [ { "uri": "file:///workspace", "name": "工作区", "metadata": { "readOnly": false, "type": "workspace" } }, { "uri": "file:///config", "name": "配置目录", "metadata": { "readOnly": true, "type": "config" } } ] } } 2. 添加根目录 请求： Code block JSON Copy { "jsonrpc": "2.0", "id": 2, "method": "roots/add", "params": { "uri": "file:///data", "name": "数据目录", "metadata": { "readOnly": false, "type": "data" } } } 3. 删除根目录 请求： Code block JSON Copy { "jsonrpc": "2.0", "id": 3, "method": "roots/remove", "params": { "uri": "file:///data" } } 4. 根目录变更通知 当根目录列表发生变化时： Code block JSON Copy { "jsonrpc": "2.0", "method": "notifications/roots/list changed" } 消息流程图 2. 添加根目录 请求： 3. 删除根目录 请求： 4. 根目录变更通知 当根目录列表发生变化时： 消息流程图 采样功能 Model Context Protocol (MCP) 为服务器提供了一种标准化的方式，通过客户端请求 LLM 采样（"补全"或"生成"）。这种流程允许客户端保持对模型访问、选择和权限的控制，同时使服务器能够利用 AI 能力 无需服务器 API 密钥。服务器可以请求文本或基于图像的交互，并可以选择在其提示中包含来自 MCP 服务器的上下文。 用户交互模型 MCP 中的采样允许服务器实现代理行为，通过使 LLM 调用能够在其他 MCP 服务器功能内部 嵌套 进行。 ⚠️ 安全提示： 为了确保信任和安全，实现方应该： • 始终让用户能够审查和拒绝采样请求 • 提供清晰的 UI 用于审查采样请求 • 允许用户在发送前查看和编辑提示 • 在传递给服务器前展示生成的响应供审查 能力声明 支持采样的客户端必须在初始化期间声明 能力： 协议消息 创建消息 要请求语言模型生成，服务器发送 sampling/createMessage 请求： 请求： 响应： 消息流程图 数据类型 消息内容 采样消息可以包含： 1. 文本内容： 2. 图片内容： 模型偏好 MCP 中的模型选择需要仔细抽象，因为服务器和客户端可能使用不同的 AI 提供商，具有不同的模型选择。服务器不能简单地通过名称请求特定模型，因为客户端可能无法访问该确切模型，或者可能更倾向于使用其他提供商的等效模型。 为了解决这个问题，MCP 实现了一个偏好系统，将抽象的能力优先级与可选的模型提示相结合： 1. 能力优先级 服务器通过三个标准化的优先级值（0 1）表达其需求： • costPriority: 最小化成本有多重要？较高的值倾向于更便宜的模型 • speedPriority: 低延迟有多重要？较高的值倾向于更快的模型 • intelligencePriority: 高级能力有多重要？较高的值倾向于更强大的模型 2. 模型提示 虽然优先级有助于基于特征选择模型，但 hints 允许服务器建议特定的模型或模型系列： • 提示被视为可以灵活匹配模型名称的子字符串 • 多个提示按优先级顺序评估 客户端可以将提示映射到不同提供商的等效模型 • 提示仅供参考 客户端做出最终的模型选择 示例： 客户端处理这些偏好以从其可用选项中选择适当的模型。例如，如果客户端无法访问 Claude 模型但有 Gemini，它可能会根据类似的功能将 sonnet 提示映射到 gemini 1.5 pro。 错误处理 客户端应该返回常见失败情况的错误： 示例： 安全考虑 1. 客户端应该： • 实现用户审批控制 • 验证消息内容 • 尊重模型偏好提示 • 实施速率限制 2. 双方必须： • 适当处理敏感数据 • 验证所有输入 • 实施访问控制 • 保护用户隐私 实现注意事项 1. 性能考虑 • 实现请求超时机制 • 处理长时间运行的生成 • 支持流式响应 • 优化并发请求 2. 可靠性 • 处理网络错误 • 实现重试机制 • 维护会话状态 • 处理部分失败 3. 可扩展性 • 支持新的模型类型 • 允许自定义偏好 • 提供模型版本控制 • 支持多提供商集成 技术实现 该协议基于 TypeScript schema 定义，提供了： • Python SDK • TypeScript SDK • 详细的用户指南 • 完整的技术规范文档 概述 Model Context Protocol (MCP) 是一个开放协议，用于实现 LLM（大型语言模型）应用程序与外部数据源和工具之间的无缝集成。无论您是在构建 AI 驱动的 IDE、增强聊天界面，还是创建自定义 AI 工作流，MCP 都提供了一种标准化的方式来连接 LLM 与其所需的上下文。 基础架构 Model Context Protocol (MCP) 采用客户端 主机 服务器架构，每个主机可以运行多个客户端实例。这种架构使用户能够在应用程序中集成 AI 功能，同时保持清晰的安全边界和关注点隔离。MCP 基于 JSON RPC 构建，提供了一个专注于客户端和服务器之间上下文交换和采样协调的有状态会话协议。 通信参与方 主机(Hosts): 发起连接的 LLM 应用程序 客户端(Clients): 主机应用程序内的连接器 服务器(Servers): 提供上下文和功能的服务 核心组件详解 架构图示 会话流程图 主机(Host) 主机进程作为容器和协调器： • 创建和管理多个客户端实例 • 控制客户端连接权限和生命周期 • 执行安全策略和同意要求 • 处理用户授权决策 • 协调 AI/LLM 集成和采样 • 管理跨客户端的上下文聚合 客户端(Clients) 每个客户端由主机创建并维护独立的服务器连接： • 与每个服务器建立一个有状态会话 • 处理协议协商和能力交换 • 双向路由协议消息 • 管理订阅和通知 • 维护服务器之间的安全边界 主机应用程序创建和管理多个客户端，每个客户端与特定服务器保持 1:1 关系。 服务器(Servers) 服务器提供专门的上下文和功能： • 通过 MCP 原语公开资源、工具和提示 • 独立运行并具有明确的职责 • 通过客户端接口请求采样 • 必须遵守安全约束 • 可以是本地进程或远程服务 设计原则 MCP 建立在几个关键设计原则之上： 1. 服务器应该极易构建 • 主机应用程序处理复杂的编排职责 • 服务器专注于特定、明确定义的功能 • 简单的接口最小化实现开销 • 清晰的分离实现可维护的代码 2. 服务器应该高度可组合 • 每个服务器独立提供专注的功能 • 多个服务器可以无缝组合 • 共享协议实现互操作性 • 模块化设计支持可扩展性 3. 服务器不应能读取整个对话，也不应"看到"其他服务器 • 服务器只接收必要的上下文信息 • 完整对话历史保留在主机 • 每个服务器连接保持隔离 • 跨服务器交互由主机控制 • 主机进程执行安全边界 4. 功能可以逐步添加到服务器和客户端 • 核心协议提供最小所需功能 • 可根据需要协商其他功能 • 服务器和客户端独立演进 • 协议设计考虑未来可扩展性 • 保持向后兼容性 消息类型 MCP 基于 JSON RPC 2.0 定义了三种核心消息类型： 请求(Requests) 请求可以从客户端发送到服务器，也可以反向发送。请求消息的格式如下： 请求消息的规则： 必须包含字符串或整数类型的 ID 与基础 JSON RPC 不同，ID 不能为 请求 ID 在同一会话中不能重复使用 响应(Responses) 响应是对请求的回复。响应消息的格式如下： 响应消息的规则： 必须包含与对应请求相同的 ID 或 必须设置其中之一，但不能同时设置两者 错误代码必须为整数 通知(Notifications) 通知可以从客户端发送到服务器，也可以反向发送。通知不需要响应。通知消息的格式如下： 通知消息的规则： 不能包含 ID 字段 每种消息类型都遵循 JSON RPC 2.0 规范的结构和传递语义。所有消息都必须严格遵守这些格式规范，以确保协议的正确实现和互操作性。 能力协商 Model Context Protocol 使用基于能力的协商系统，客户端和服务器在初始化期间明确声明其支持的功能。能力决定了会话期间可用的协议功能和原语。 • 服务器声明资源订阅、工具支持和提示模板等功能 • 客户端声明采样支持和通知处理等功能 • 双方必须在整个会话期间遵守声明的功能 • 可以通过协议扩展协商其他功能 每个能力都会解锁会话期间使用的特定协议功能。例如： • 已实现的服务器功能必须在服务器的能力中公布 • 发出资源订阅通知需要服务器声明订阅支持 • 工具调用需要服务器声明工具能力 • 采样需要客户端在其能力中声明支持 这种能力协商确保客户端和服务器在维护协议可扩展性的同时，对支持的功能有清晰的理解。 基础协议特性 1. 使用 JSON RPC 2.0 消息格式 2. 支持有状态连接 3. 服务器和客户端能力协商 核心功能 服务器功能 服务器可以向客户端提供以下功能： 1. 资源(Resources) • 为用户或 AI 模型提供上下文和数据使用 • 支持以下功能： ◦ 资源列表和元数据查询 ◦ 资源内容读取和订阅 ◦ 资源变更通知 ◦ 资源搜索和过滤 ◦ 资源列表和元数据查询 ◦ 资源内容读取和订阅 ◦ 资源变更通知 ◦ 资源搜索和过滤 • 资源类型包括： ◦ 文件和目录 ◦ 数据库记录 ◦ API 端点 ◦ 配置项 ◦ 文件和目录 ◦ 数据库记录 ◦ API 端点 ◦ 配置项 2. 提示(Prompts) • 为用户提供模板化消息和工作流 • 功能特性： ◦ 提示模板管理 ◦ 变量插值和验证 ◦ 多语言支持 ◦ 版本控制 ◦ 提示模板管理 ◦ 变量插值和验证 ◦ 多语言支持 ◦ 版本控制 • 使用场景： ◦ 标准化用户交互 ◦ 工作流自动化 ◦ 多步骤操作指导 ◦ 错误处理和恢复 ◦ 标准化用户交互 ◦ 工作流自动化 ◦ 多步骤操作指导 ◦ 错误处理和恢复 3. 工具(Tools) • 供 AI 模型执行的功能函数 • 核心特性： ◦ 参数验证和类型检查 ◦ 参数验证和类型检查 ◦ 异步执行支持 ◦ 错误处理和重试 ◦ 进度报告 • 安全考虑： ◦ 权限控制 ◦ 资源限制 ◦ 执行隔离 ◦ 审计日志 ◦ 权限控制 ◦ 资源限制 ◦ 执行隔离 ◦ 审计日志 资源管理 资源能力声明 支持资源的服务器必须在初始化期间声明其资源能力： 能力字段说明： • subscribe: 是否支持资源订阅 • listChanged: 是否支持资源列表变更通知 • search: 是否支持资源搜索 • metadata: 是否支持元数据查询 资源类型 MCP 定义了以下标准资源类型： 1. 文件系统资源 2. 目录资源 3. 数据库资源 4. API 资源 资源操作 1. 列表查询 请求： 响应： 2. 资源读取 请求： 响应： 3. 资源搜索 请求： 响应： 4. 资源订阅 请求： 响应： 变更通知： 错误处理 服务器必须使用标准的 JSON RPC 错误代码： 4. 资源不存在： 5. 访问被拒绝： 6. 无效的请求参数： 实现注意事项 1. 性能考虑 • 实现分页以处理大量资源 • 缓存频繁访问的资源 • 优化搜索索引 • 限制订阅数量 2. 安全考虑 • 验证所有资源访问权限 • 实施资源访问控制 • 保护敏感资源元数据 • 限制资源操作范围 3. 可靠性 • 处理资源锁定情况 • 实现重试机制 • 保持订阅状态一致性 • 处理网络错误 资源生命周期 提示管理 Model Context Protocol (MCP) 为服务器提供了一种标准化的方式来向客户端公开提示模板。提示允许服务器提供结构化的消息和指令，用于与语言模型进行交互。客户端可以发现可用的提示、检索其内容并提供参数来自定义它们。 用户交互模型 提示设计为用户控制的机制，这意味着它们从服务器暴露给客户端时，用户能够明确地选择使用它们。 典型的使用场景包括： • 通过斜杠命令触发（如 /code review） • 在用户界面中的菜单选项 • 上下文相关的快捷操作 • 工作流程自动化步骤 能力声明 支持提示的服务器必须在初始化期间声明 能力： 其中 listChanged 表示服务器是否会在可用提示列表发生变化时发送通知。 提示模板 提示模板定义了标准化的交互模式，支持以下功能： 1. 基本信息 2. 消息内容 提示消息可以包含以下类型的内容： 文本内容： 图片内容： 嵌入资源： 提示操作 1. 列表查询：获取可用提示列表（支持分页） 2. 获取提示：检索特定提示的内容 3. 列表变更通知：当可用提示列表发生变化时 消息流程图 错误处理 服务器应该返回标准的 JSON RPC 错误： 7. 无效的提示名称： 8. 缺少必需参数： 实现注意事项 9. 参数验证 服务器必须在处理前验证所有提示参数 客户端应该实现参数自动完成功能 参数类型必须符合声明的类型 10. 性能考虑 客户端应该处理大型提示列表的分页 服务器应该缓存常用提示模板 双方应该遵守能力协商结果 安全考虑 11. 输入验证 所有提示输入必须经过严格验证 • 防止注入攻击和越权访问 • 验证嵌入资源的安全性 12. 访问控制 ◦ 实现适当的权限检查 ◦ 限制敏感提示的访问 ◦ 记录提示使用情况 ◦ 实现适当的权限检查 ◦ 限制敏感提示的访问 ◦ 记录提示使用情况 13. 资源限制 ◦ 限制提示大小和复杂度 ◦ 控制嵌入资源的数量 ◦ 实施速率限制 ◦ 限制提示大小和复杂度 ◦ 控制嵌入资源的数量 ◦ 实施速率限制 工具执行 Model Context Protocol (MCP) 允许服务器向语言模型公开可调用的工具。工具使模型能够与外部系统交互，例如查询数据库、调用 API 或执行计算。每个工具都有唯一的名称标识和描述其模式的元数据。 用户交互模型 工具设计为模型控制的机制，这意味着语言模型可以根据其上下文理解和用户提示自动发现和调用工具。 ⚠️ 安全提示： 为了确保信任和安全，实现方应该： • 提供清晰的 UI 显示哪些工具对 AI 模型可用 • 在工具被调用时插入明显的视觉指示 • 为操作提供用户确认提示，确保有人为参与 能力声明 支持工具的服务器必须在初始化期间声明 能力： 其中 listChanged 表示服务器是否会在可用工具列表发生变化时发送通知。 工具定义 每个工具都有明确的接口定义： 工具操作 1. 工具列表查询 请求： 响应： 2. 工具调用 请求： 响应： 3. 列表变更通知 当可用工具列表发生变化时： 消息流程图 数据类型 1. 工具结果 工具结果可以包含多种类型的内容： 文本内容： 图片内容： 嵌入资源： 错误处理 工具使用两种错误报告机制： 1. 协议错误：标准的 JSON RPC 错误，用于： • 未知工具 • 无效参数 • 服务器错误 示例： 2. 工具执行错误：在工具结果中通过 报告： • API 调用失败 • 输入数据无效 • 业务逻辑错误 示例： 安全考虑 1. 服务器必须： • 验证所有工具输入 • 实施适当的访问控制 • 限制工具调用频率 • 净化工具输出 2. 客户端应该： • 对敏感操作请求用户确认 • 在调用服务器前向用户展示工具输入，以防止恶意或意外的数据泄露 • 在传递给 LLM 前验证工具结果 • 为工具调用实现超时机制 • 记录工具使用情况以供审计 实现注意事项 1. 性能考虑 • 实现工具调用的超时机制 • 缓存频繁使用的工具结果 • 优化长时间运行的操作 • 实施并发控制 2. 可靠性 • 处理网络错误和超时 • 实现重试机制 • 提供清晰的错误信息 • 维护工具状态一致性 3. 可扩展性 • 支持动态工具注册 • 允许工具版本控制 • 提供工具依赖管理 • 支持工具组合 客户端功能 客户端可以向服务器提供： 采样(Sampling) • 服务器发起的主动行为 • 递归 LLM 交互 实用工具 • 配置管理 • 进度跟踪 • 取消操作 • 错误报告 • 日志记录 自动完成 Model Context Protocol (MCP) 提供了一种标准化的方式，使服务器能够为提示参数和资源 URI 提供参数自动完成建议。这使得用户能够获得类似 IDE 的体验，在输入参数值时获得上下文相关的建议。 用户交互模型 自动完成功能设计用于支持类似 IDE 代码补全的交互体验： • 用户输入时在下拉菜单或弹出窗口中显示建议 • 支持实时过滤和选择可用选项 • 实现可以根据需要采用任何合适的界面模式 协议消息 请求自动完成 客户端通过发送 completion/complete 请求来获取补全建议： 服务器响应： 引用类型 协议支持两种类型的补全引用： 类型 描述 示例 ref/prompt 通过名称引用提示 {"type": "ref/prompt", "name": "code review"} ref/resource 引用资源 URI {"type": "ref/resource", "uri": "file:///{path}"} 类型 类型 描述 描述 示例 示例 ref/prompt ref/prompt 通过名称引用提示 通过名称引用提示 {"type": "ref/prompt", "name": "code review"} {"type": "ref/prompt", "name": "code review"} ref/resource ref/resource 引用资源 URI 引用资源 URI {"type": "ref/resource", "uri": "file:///{path}"} {"type": "ref/resource", "uri": "file:///{path}"} 补全结果 服务器返回按相关性排序的补全值数组： • 每个响应最多包含 100 个项目 • 可选的可用匹配总数 • 布尔值表示是否存在更多结果 消息流程 数据类型 CompleteRequest • ref: PromptReference 或 ResourceReference • argument: 包含以下字段的对象： ◦ name: 参数名称 ◦ value: 当前值 ◦ name: 参数名称 ◦ value: 当前值 CompleteResult • completion: 包含以下字段的对象： ◦ values: 建议数组（最多 100 个） ◦ total: 可选的匹配总数 ◦ hasMore: 是否有更多结果的标志 ◦ values: 建议数组（最多 100 个） ◦ total: 可选的匹配总数 ◦ hasMore: 是否有更多结果的标志 实现注意事项 1. 服务器应该： • 按相关性排序返回建议 • 在适当情况下实现模糊匹配 • 限制补全请求频率 • 验证所有输入 2. 客户端应该： • 对快速补全请求进行去抖动处理 • 适当缓存补全结果 • 优雅处理缺失或部分结果 安全考虑 实现必须： • 验证所有补全输入 • 实施适当的速率限制 • 控制对敏感建议的访问 • 防止基于补全的信息泄露 传输机制 MCP 目前定义了两种标准的客户端 服务器通信传输机制： 14. stdio：通过标准输入输出进行通信 15. HTTP with Server Sent Events (SSE)：使用 HTTP 和服务器发送事件 客户端应该尽可能支持 stdio 传输。此外，客户端和服务器也可以以可插拔的方式实现自定义传输。 stdio 传输 在 stdio 传输中： • 客户端将 MCP 服务器作为子进程启动 • 服务器在其标准输入（stdin）上接收 JSON RPC 消息，并将响应写入其标准输出（stdout） 消息由换行符分隔，并且不能包含嵌入的换行符 服务器可以将 UTF 8 字符串写入其标准错误（ ）用于日志记录。客户端可以捕获、转发或忽略此日志 服务器不能向其 写入任何不是有效 MCP 消息的内容 客户端不能向服务器的 写入任何不是有效 MCP 消息的内容 HTTP with SSE 传输 在 SSE 传输中，服务器作为独立进程运行，可以处理多个客户端连接。 服务器必须提供两个端点： 16. SSE 端点：供客户端建立连接并接收来自服务器的消息 17. 常规 HTTP POST 端点：供客户端向服务器发送消息 当客户端连接时，服务器必须发送一个包含 URI 的 事件，客户端用该 URI 发送消息。所有后续的客户端消息必须作为 HTTP POST 请求发送到此端点。 服务器消息作为 SSE message 事件发送，消息内容在事件数据中以 JSON 编码。 自定义传输 客户端和服务器可以实现额外的自定义传输机制以满足其特定需求。协议与传输无关，可以在任何支持双向消息交换的通信通道上实现。 选择支持自定义传输的实现者必须确保它们保留 MCP 定义的 JSON RPC 消息格式和生命周期要求。自定义传输应该记录其特定的连接建立和消息交换模式以帮助互操作性。 安全性和信任 核心原则 1. 用户同意和控制 • 用户必须明确同意并理解所有数据访问和操作 • 用户必须保持对数据共享和操作的控制权 • 实施方应提供清晰的用户界面用于审查和授权活动 2. 数据隐私 • 主机在向服务器暴露用户数据前必须获得明确同意 • 未经用户同意，主机不得传输资源数据 • 用户数据应受到适当的访问控制保护 3. 工具安全 • 工具代表任意代码执行，必须谨慎对待 • 主机在调用任何工具前必须获得用户明确同意 • 用户应在授权使用前理解每个工具的功能 4. LLM 采样控制 • 用户必须明确批准任何 LLM 采样请求 • 用户应控制： ◦ 是否进行采样 ◦ 实际发送的提示 ◦ 服务器可以看到的结果 ◦ 是否进行采样 ◦ 实际发送的提示 ◦ 服务器可以看到的结果 实施指南 实施方应当： 18. 在应用程序中构建健全的同意和授权流程 19. 提供清晰的安全影响文档 20. 实施适当的访问控制和数据保护 21. 在集成中遵循安全最佳实践 22. 在功能设计中考虑隐私影响 分页 Model Context Protocol (MCP) 支持对可能返回大量结果集的列表操作进行分页。分页允许服务器以较小的块而不是一次性返回所有结果。 这在通过互联网连接外部服务时尤其重要，但对于本地集成来说也很有用，可以避免大数据集带来的性能问题。 分页模型 MCP 中的分页使用基于不透明游标的方法，而不是使用页码： 游标是一个不透明的字符串令牌，表示结果集中的位置 页面大小由服务器确定，并且可能不是固定的 响应格式 当服务器发送包含以下内容的响应时，分页开始： • 当前页面的结果 • 如果存在更多结果，则包含可选的 nextCursor 字段 请求格式 收到游标后，客户端可以通过发出包含该游标的请求来 继续 分页： 分页流程 支持分页的操作 以下 MCP 操作支持分页： • resources/list 列出可用资源 • resources/templates/list 列出资源模板 • prompts/list 列出可用提示 • tools/list 列出可用工具 实现指南 1. 服务器应该： • 提供稳定的游标 • 优雅地处理无效游标 2. 客户端应该： • 将缺失的 nextCursor 视为结果的结束 • 同时支持分页和非分页流程 3. 客户端必须将游标视为不透明令牌： • 不对游标格式做任何假设 • 不尝试解析或修改游标 • 不在会话之间保留游标 错误处理 无效的游标应该导致错误代码为 32602（无效参数）的错误。 示例： 性能考虑 1. 服务器应该： • 为大型结果集优化分页查询 • 实现适当的缓存策略 • 限制单页最大大小 2. 客户端应该： • 实现请求节流 • 适当缓存结果 • 处理网络延迟和错误 安全考虑 实现必须： • 验证所有游标输入 • 防止通过游标操作进行的信息泄露 • 实施适当的速率限制 • 保护敏感数据不被未授权访问 参考资料 所有详细信息可在 modelcontextprotocol.io 官方网站找到，包括： modelcontextprotocol.io • 架构详细说明 • 基础协议文档 • 服务器功能说明 • 客户端功能文档 • 贡献指南 这份规范为 AI 应用生态系统提供了标准化的集成方案，类似于编程语言领域的 Language Server Protocol (LSP)，使得 AI 应用能够更好地与各种工具和数据源进行交互。 生命周期管理 Model Context Protocol (MCP) 为客户端 服务器连接定义了严格的生命周期，以确保正确的能力协商和状态管理。 生命周期流程图