MCP协议
定义
模型上下文协议(Model Context Protocol,MCP)是建立在 JSON-RPC 2.0 之上的应用层协议,它规定宿主应用如何为每个外部能力提供者建立独立连接,如何在连接开始时协商协议版本与能力集合,如何枚举并调用该提供者的工具、资源与提示模板,以及如何用统一的内容块结构返回调用结果。
一次 MCP 会话可记为六元组 。本篇出现的符号如下表,其中 是某个 Server 的能力集合, 是消息字段。
| 符号 | 含义 |
|---|---|
| Host,宿主应用进程,持有模型、用户界面与权限策略 | |
| Client,Host 内为一个 Server 建立的连接对象,与 Server 一一对应 | |
| Server,提供工具、资源或提示模板的进程或远程服务 | |
| 传输通道,取 stdio 或 HTTP 两类之一 | |
协议版本,形如 2025-06-18 的日期字符串 | |
| 握手后双方各自声明并接受的能力集合 | |
| 某个 Server 的工具集合、资源集合、提示模板集合 | |
| JSON-RPC 请求标识,同一会话内唯一,用于匹配响应 |
术语按首次出现处定义:工具(tool)是 Server 暴露的可执行函数,具有名称、说明与输入模式;资源(resource)是可由 URI 定位的只读上下文数据;提示模板(prompt)是带参数的、可复用的消息序列;能力(capability)是双方在 initialize 中声明的功能集合,声明后才允许使用对应方法;内容块(content block)是工具结果与消息内容的基本单元,type 取 text、image、audio、resource_link 或 resource;通知(notification)是无 id、不要求回复的 JSON-RPC 消息。
协议版本是日期字符串,版本之间可以增删字段。本篇以 2025-06-18 版为准;该版的三个部分,即 JSON-RPC 消息层、initialize 握手、三类原语,在前后版本中保持稳定。
为什么重要
集成成本随宿主应用数与能力提供者数的乘积增长。设宿主应用有 种、能力提供者有 种,若每对组合都需要专门适配,需要实现的适配器数量为
而协议化之后,每一侧只需实现一次协议,适配器数量降为
取 、,前者为 160,后者为 28。该对比只统计传输、序列化、能力发现、生命周期与错误格式的复用;它不减少语义映射的工作量,因为每个 Server 仍必须定义自己的工具语义与输入模式。把 理解为"所有集成都变简单"是过度推断,正确的结论是:重复的工程部分被收敛到协议层,剩下的部分按 Server 计一次。
没有协议会产生四类具体后果。第一类是发现成本:宿主无法在运行时知道某个数据源提供哪些能力,工具清单必须硬编码并随提供者升级重新发版。第二类是权限成本:每个适配器自行决定何时请求用户同意,同意粒度、展示内容与撤销方式各不相同,无法审计。第三类是生命周期成本:连接建立、版本不匹配、进程崩溃、请求取消各自实现一套,边界情况覆盖不全。第四类是组合成本:一个宿主连接多个提供者时,工具重名、错误码冲突、超时语义不一致没有统一的解决位置。
MCP 在本库中的位置是能力层。AI-Agent与工具调用 讨论单次工具调用的模式与回填,结构化输出 讨论输入模式所用的 JSON Schema 语义,本篇讨论这些能力如何跨进程被发现与调用;Harness与Loop工程 则把 Client 视为工具执行层的一个后端,在其上实现循环、预算与轨迹。对应学习目标中的"能复现"与"会评估":能写出一个可被宿主加载的 Server,能判断一次失败发生在传输层、协议层还是工具执行层。
原理与推导
1 三个角色与连接拓扑
三个角色的职责边界由一条不变量确定:Server 不能直接访问模型,Server 之间互不可见,只有 Host 同时持有模型输出与全部连接。由此可以确定三个角色各自的职责范围。
Host 的职责有四项:维护会话与模型调用;为每个 Server 创建并维护一个 Client;聚合所有 Server 的能力清单并处理命名冲突;在执行前完成权限检查与用户同意。Client 的职责是连接级的:编解码、分配请求 id、匹配响应与通知、维护该连接的生命周期状态。Server 的职责是能力级的:声明能力、响应枚举与调用、主动发送变更通知;需要模型或文件系统边界时,通过反向请求 sampling/createMessage 或 roots/list 向 Client 索取。
flowchart LR
U[用户] --> H[Host 宿主应用]
H --> C1[Client 1]
H --> C2[Client 2]
C1 <-->|stdio| S1[Server 文件系统]
C2 <-->|HTTP+SSE| S2[Server 数据库]
一次工具调用的消息序列如下。注意 notifications/initialized 没有响应,Client 发送后不等待。
sequenceDiagram
participant H as Host
participant C as Client
participant S as Server
participant M as 模型
C->>S: initialize(protocolVersion, capabilities)
S-->>C: result(protocolVersion, capabilities, serverInfo)
C->>S: notifications/initialized
C->>S: tools/list
S-->>C: result(tools[...])
H->>M: 请求(含工具清单)
M-->>H: 调用意图 add(a=19, b=23)
H->>H: 权限检查与用户同意
H->>C: tools/call
C->>S: tools/call(name, arguments)
S-->>C: result(content, isError)
H->>M: 回填工具结果
命名空间是聚合的直接结果。两个 Server 都可能提供名为 search 的工具,Host 必须为每个工具生成唯一标识,例如 serverA.search 与 serverB.search,并在把调用意图发回模型之前完成反向映射。若不做这一步,后注册的工具会覆盖先注册的工具,表现为"模型调用了错误的实现"。
2 传输层
传输层只负责消息边界,不负责重试与顺序。消息按行分隔,每条消息占一行,请求与响应通过 id 关联,因此同一连接上可以有多个未完成请求,响应可以乱序到达。
stdio 的规则如下。Host 以子进程方式启动 Server,Server 从标准输入读取消息、向标准输出写出消息,标准错误用于日志。每条消息是一行 UTF-8 编码的 JSON,以 \n 结束,JSON 字符串内部的换行必须转义,否则会被拆成两条消息。stdio 没有内建认证,Server 以宿主用户的权限运行,安全边界由操作系统提供。会话结束时 Host 关闭子进程的标准输入,Server 读到 EOF 后退出;Host 应设置退出等待上限,超时后终止进程。
stdio 适用于本地能力:文件系统、本地数据库、命令行工具、需要读取用户机器状态的服务。它不适用于多租户共享或需要独立扩缩容的场景,因为每个用户都需要一个进程,权限与配额无法在协议层区分。
HTTP 传输有两代,差异在端点数量与会话标识。下表对比三者。
| 维度 | stdio | HTTP+SSE(2024-11-05) | Streamable HTTP(2025-03-26 起) |
|---|---|---|---|
| 端点 | 子进程的 stdin/stdout | 两个:GET 事件流端点与 POST 消息端点 | 一个:POST 与 GET 使用同一 URL |
| 客户端到服务端 | 写入 stdin,每行一条 JSON | POST 到消息端点,返回 202 | POST 单条消息,响应为 JSON 或 SSE |
| 服务端到客户端 | 写入 stdout | GET 建立的 SSE 流 | POST 的 SSE 响应,或独立的 GET 流 |
| 认证 | 无,依赖进程权限 | 规范未定义,部署方自定 | OAuth 2.1 持有者令牌 |
| 会话标识 | 进程本身 | 无标准头 | Mcp-Session-Id 响应头 |
| 断线恢复 | 无,进程退出即结束 | 需重新建立两条连接 | Last-Event-ID 续传 |
| 适用 | 本地工具、文件、CLI | 兼容旧实现 | 远程共享服务、多租户、集中审计 |
| 主要风险 | 任意本地代码执行 | 连接关联困难 | DNS 重绑定、会话劫持、混淆代理 |
Streamable HTTP 的协议细节包括:服务端若分配会话,在 initialize 的响应中通过 Mcp-Session-Id 头返回,后续请求必须携带该头;客户端在后续请求中携带 MCP-Protocol-Version 头声明版本;服务端对不存在的会话返回 404,客户端必须重新握手;服务端不支持 GET 流时返回 405;事件流中的消息带 id 字段,客户端用 Last-Event-ID 请求续传。远程部署还必须校验 Origin 头、在本地部署时绑定回环地址、在公网部署时启用 TLS,否则浏览器页面可以借助用户的本机连接发起跨站请求。
3 JSON-RPC 2.0 消息格式
MCP 的全部消息都是 JSON-RPC 2.0 对象,共三种。
请求携带 id、method、params,接收方必须回复一条 id 相同的响应:
{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "add", "arguments": {"a": 19, "b": 23}}}
成功响应只含 result,失败响应只含 error,二者互斥:
{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "{\"sum\": 42}"}], "isError": false}}
{"jsonrpc": "2.0", "id": 1, "error": {"code": -32602, "message": "Invalid params",
"data": {"field": "arguments.a"}}}
通知没有 id,接收方不得回复。MCP 的通知方法名统一以 notifications/ 为前缀:
{"jsonrpc": "2.0", "method": "notifications/initialized"}
规则可以归纳为八条。第一,jsonrpc 字段固定为字符串 "2.0"。第二,请求的 id 必须存在且不为 null,取字符串或数字,同一会话内不得复用尚未完成的 id。第三,id 是匹配响应的唯一依据,Host 必须维护 id 到连接、方法名与截止时间的映射表。第四,响应必须有且只有一个 result 或 error。第五,通知没有 id,不得回复,也不参与 id 映射。第六,params 为对象,MCP 全部使用具名参数。第七,JSON-RPC 允许把多条消息打包为数组,MCP 在 2025-03-26 版允许批量请求,在 2025-06-18 版移除,因此实现不得依赖批量。第八,JSON-RPC 不保证响应顺序,也不要求请求串行,实现必须容忍乱序与并发。
4 初始化握手与能力协商
握手由三条消息构成,缺一不可。
{"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {"roots": {"listChanged": true}, "sampling": {}},
"clientInfo": {"name": "example-host", "version": "0.1.0"}}}
{"jsonrpc": "2.0", "id": 1, "result": {
"protocolVersion": "2025-06-18",
"capabilities": {"tools": {"listChanged": true},
"resources": {"subscribe": true, "listChanged": true}},
"serverInfo": {"name": "example-server", "version": "1.4.2"},
"instructions": "文件系统中的笔记可通过 resources 读取。"}}
{"jsonrpc": "2.0", "method": "notifications/initialized"}
版本协商按以下步骤执行。第一步,Client 发送自己支持的最新版本 。第二步,Server 若支持 则原样返回,否则返回自己支持的一个版本 。第三步,Client 检查 是否在自己支持的集合内,不支持则断开连接,不得按未声明版本继续通信。第四步,双方按对方声明的能力集合决定可用方法,未声明能力对应的方法不得调用。第五步,Client 发送 notifications/initialized,会话进入正常阶段。
能力集合的内容如下表。listChanged 表示该集合变化时会发送通知,Host 收到后必须重新枚举。
| 方向 | 能力 | 附加字段 | 对应方法与通知 |
|---|---|---|---|
| Client | roots | listChanged | roots/list、notifications/roots/list_changed |
| Client | sampling | 无 | sampling/createMessage |
| Client | elicitation | 无 | elicitation/create |
| Server | tools | listChanged | tools/list、tools/call、notifications/tools/list_changed |
| Server | resources | subscribe、listChanged | resources/list、resources/templates/list、resources/read、resources/subscribe |
| Server | prompts | listChanged | prompts/list、prompts/get、notifications/prompts/list_changed |
| Server | logging | 无 | logging/setLevel、notifications/message |
| Server | completions | 无 | completion/complete |
三条时序规则决定握手阶段的行为边界。initialize 在每个会话中只能发送一次,重复发送属于非法请求。Client 在收到 initialize 响应之前只应发送 ping,其余请求应等待。Server 在收到 notifications/initialized 之前只应发送 ping 与日志消息,不得主动发起其他请求。
能力声明的工程后果是界面不能静态绑定功能。Host 只有在握手完成后才知道某个 Server 是否提供资源,因此资源面板、工具菜单与审批界面都必须在握手后按能力集合动态生成;把 resources 写死在界面里,在连接只提供工具的 Server 时会产生空面板与无效调用。
5 工具原语
工具由模型选择调用,这是它与资源、提示模板在控制权上的根本差异。tools/list 返回工具数组,每个工具对象包含名称、可选标题、说明、输入模式与行为提示。
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}
{"jsonrpc": "2.0", "id": 2, "result": {"tools": [{
"name": "add",
"title": "两数相加",
"description": "返回两个数字 a 与 b 的和,结果绝对值不得超过 1000。",
"inputSchema": {
"type": "object",
"properties": {"a": {"type": "number"}, "b": {"type": "number"}},
"required": ["a", "b"],
"additionalProperties": false},
"outputSchema": {"type": "object",
"properties": {"sum": {"type": "number"}},
"required": ["sum"]},
"annotations": {"readOnlyHint": true, "destructiveHint": false,
"idempotentHint": true, "openWorldHint": false}}]}}
inputSchema 是 JSON Schema 对象,默认值为 {"type": "object"}。outputSchema 在 2025-06-18 版加入,用于声明 structuredContent 的结构;声明了输出模式的工具应当同时在 content 中返回序列化后的 JSON 文本,以兼容只读取文本内容的客户端。annotations 是行为提示,readOnlyHint、destructiveHint、idempotentHint、openWorldHint 均不具强制性,Host 必须自行判断是否需要用户确认。
调用与结果如下。结果中的 content 是内容块数组,isError 标记工具执行是否失败。
{"jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": {"name": "add", "arguments": {"a": 19, "b": 23}}}
{"jsonrpc": "2.0", "id": 3, "result": {
"content": [{"type": "text", "text": "{\"sum\": 42}"}],
"structuredContent": {"sum": 42},
"isError": false}}
内容块类型与必填字段如下表。
type | 必填字段 | 用途 |
|---|---|---|
text | text | 纯文本结果 |
image | data、mimeType | base64 编码图像 |
audio | data、mimeType | base64 编码音频 |
resource_link | uri、name | 引用资源,不内联内容 |
resource | resource 对象,含 uri 与 text 或 blob | 内联资源内容 |
错误分两个通道,分工必须明确。参数不符合 inputSchema、工具名不存在、方法未实现属于协议层错误,用 JSON-RPC error 返回,因为这类错误说明调用方与 Server 的约定不一致,模型无法通过重试修正。工具已执行但业务失败,例如目标不存在、下游服务拒绝、输入超出业务范围,用 result 加 isError: true 返回,并在 content 中给出可读原因,使模型能够修改参数后重试。把业务错误放进 JSON-RPC error 会让模型看不到原因,把协议错误放进 isError 会让 Host 误以为工具存在。
工具名是跨 Server 的全局命名空间问题。规范建议名称为 1 至 128 个字符,只含字母、数字、下划线、连字符与点,且区分大小写。Host 聚合多个 Server 时应加前缀,并在工具定义变化时使旧批准失效。
6 资源原语
资源由应用控制,Host 决定哪些资源进入上下文,模型不直接读取。resources/list 返回资源描述,resources/read 按 URI 读取内容。
{"jsonrpc": "2.0", "id": 4, "method": "resources/list"}
{"jsonrpc": "2.0", "id": 4, "result": {"resources": [{
"uri": "file:///notes/08/MCP%E5%8D%8F%E8%AE%AE.md",
"name": "MCP协议.md",
"mimeType": "text/markdown",
"annotations": {"audience": ["assistant"], "priority": 0.8,
"lastModified": "2026-10-18T12:00:00Z"}}]}}
模板用于描述一族 URI,参数按 RFC 6570 展开。resources/templates/list 返回模板,Host 在用户选择具体参数后调用 resources/read。
{"jsonrpc": "2.0", "id": 5, "method": "resources/templates/list"}
{"jsonrpc": "2.0", "id": 5, "result": {"resourceTemplates": [{
"uriTemplate": "file:///notes/{stage}/{name}.md",
"name": "笔记",
"mimeType": "text/markdown"}]}}
读取结果是一个 contents 数组,每项含 uri、可选 mimeType,以及 text 或 blob 之一。URI 不存在时返回错误码 -32002。资源支持订阅:Client 发送 resources/subscribe 后,Server 在内容变化时发送 notifications/resources/updated,其参数包含变化的 uri;资源集合本身变化时发送 notifications/resources/list_changed。
资源与工具的分工可以用一次往返是否必要来判断。只读且 Host 能预先确定需要的上下文,应当在构造消息时直接读取并注入,省去一次模型决策与工具往返;需要模型根据中间结果决定读什么,才应包装为工具。资源的代价是 Host 必须理解 URI 语义并处理注入内容,工具结果与资源内容在安全性上没有区别,两者都可能携带提示注入。
7 提示原语
提示模板由用户控制,典型形态是斜杠命令或模板菜单。prompts/list 返回模板及其参数,prompts/get 按名称与参数展开为消息序列。
{"jsonrpc": "2.0", "id": 6, "method": "prompts/list"}
{"jsonrpc": "2.0", "id": 6, "result": {"prompts": [{
"name": "review-note",
"title": "审查笔记",
"description": "按规范检查一篇笔记的结构与链接。",
"arguments": [{"name": "path", "description": "笔记路径", "required": true}]}]}}
{"jsonrpc": "2.0", "id": 7, "method": "prompts/get",
"params": {"name": "review-note", "arguments": {"path": "08-Agent与工程化/MCP协议.md"}}}
{"jsonrpc": "2.0", "id": 7, "result": {
"description": "审查笔记",
"messages": [{"role": "user",
"content": {"type": "text", "text": "检查 08-Agent与工程化/MCP协议.md 的结构。"}}]}}
模板参数由 Host 或用户填充,不由模型生成,这与工具参数的控制方相反。三类原语的差异汇总如下。
| 原语 | 控制方 | 发现方法 | 调用方法 | 结果是否进入模型上下文 |
|---|---|---|---|---|
| 工具 | 模型 | tools/list | tools/call | 是 |
| 资源 | 应用 | resources/list、resources/templates/list | resources/read | 由应用决定 |
| 提示模板 | 用户 | prompts/list | prompts/get | 是,展开为消息 |
8 采样与根
采样让 Server 借用 Host 的模型,从而不必自带上游 API 密钥。方向是 Server 到 Client 的请求:
{"jsonrpc": "2.0", "id": 8, "method": "sampling/createMessage",
"params": {
"messages": [{"role": "user", "content": {"type": "text", "text": "概括这段日志。"}}],
"modelPreferences": {"hints": [{"name": "claude"}],
"costPriority": 0.3, "speedPriority": 0.2,
"intelligencePriority": 0.5},
"systemPrompt": "只输出中文摘要。",
"includeContext": "none",
"maxTokens": 256,
"temperature": 0.2}}
结果包含 role、content、model 与 stopReason。modelPreferences 是偏好而非指定,最终模型由 Host 选择。includeContext 取 none、thisServer 或 allServers,取 allServers 时 Host 会把其他 Server 的上下文提供给模型,这会造成跨信任域的数据泄露,默认应取 none 或 thisServer。规范要求采样请求应保留人工审查与拒绝的能力。
根用于声明文件系统边界。Client 收到 Server 的 roots/list 请求后返回根目录列表:
{"jsonrpc": "2.0", "id": 9, "result": {"roots": [
{"uri": "file:///D:/DSH_Workspace/AIlearning", "name": "AIlearning"}]}}
根发生变化时 Client 发送 notifications/roots/list_changed。根是建议性边界,不是访问控制:Server 必须自行做路径规范化与前缀校验,否则 file:///root/../etc/passwd 这类路径可以逃逸。把根当作沙箱使用是集成阶段的高危错误。
9 生命周期、取消、进度与超时
会话状态可以划分为四个阶段。
| 状态 | 允许的消息 | 迁移条件 |
|---|---|---|
| 未初始化 | initialize、ping | 收到 initialize 请求 |
| 握手中 | initialize 响应、notifications/initialized、ping | 收到 notifications/initialized |
| 就绪 | 全部已声明能力对应的方法 | 传输关闭或致命错误 |
| 关闭 | 无 | 进程退出或连接释放 |
ping 可由任一方发送,响应为空结果,用于探活。
取消是协作式的通知:请求方发送 notifications/cancelled,参数包含待取消请求的 requestId 与可选 reason;接收方应停止处理并释放资源,且不得再为该请求发送响应;若响应已经发出,发送方应忽略。initialize 不得被取消,因为版本与能力协商失败会使整个会话失去语义。取消无法撤销已经发生的副作用,也无法强制中断不可抢占的工具执行,因此 Host 仍必须在执行层设置硬超时。
进度用于长任务。请求在 params._meta.progressToken 中携带令牌,接收方发送 notifications/progress,参数含 progressToken、累计的 progress、可选 total 与 message。progress 是累计值而非增量,重复的令牌对应同一个任务。
协议不规定超时时长。Host 应为每个请求设置截止时间,超时后发送取消通知、丢弃迟到响应、释放 id 映射,并把该步骤标记为超时;Server 应把截止时间传递给下游调用,否则 Host 已经放弃而 Server 仍在消耗资源。
会话结束没有专门的关闭方法。stdio 下 Host 关闭标准输入,Server 读到 EOF 后退出,Host 等待退出,超时后终止进程;HTTP 下 Host 终止会话或关闭事件流,服务端清理会话状态。
10 错误模型
错误分布在三层,处理方式不同。
| 层 | 表现 | 典型原因 | 处理 |
|---|---|---|---|
| 传输层 | 连接断开、JSON 解析失败 | 日志写入标准输出、编码不一致 | 终止会话、记录原始字节、修正 Server |
| 协议层 | JSON-RPC error 对象 | 参数不合法、方法不存在、未初始化 | 转为失败步骤,不自动重试 |
| 执行层 | result.isError 为真 | 下游超时、目标不存在、权限不足 | 可重试、回填模型修正、终止 |
JSON-RPC 与 MCP 使用的错误码如下表。
| 码 | 名称 | 触发条件 |
|---|---|---|
-32700 | Parse error | 收到非 JSON 文本 |
-32600 | Invalid Request | 缺少必需字段、id 非法、消息不是合法请求 |
-32601 | Method not found | 方法未实现 |
-32602 | Invalid params | 参数不符合模式、工具名不存在 |
-32603 | Internal error | 服务端内部异常 |
-32002 | Resource not found | resources/read 的 URI 不存在 |
-32000 至 -32099 | 实现自定义 | 服务端定义的业务错误,应在 data 中说明 |
Host 的职责是把协议层错误转换成模型可理解的信息。模型只看到会话消息,看不到 JSON-RPC 错误对象,因此 Host 必须把错误码与原因写入一条工具结果消息,并标注这是协议失败而非业务失败,否则模型会反复用同样的参数重试。
11 权限、同意与安全风险
用户同意是协议的强制环节,不是界面装饰。Host 在调用前应展示 Server 身份、工具名与完整参数,对具有破坏性的操作每次确认,对只读操作可按会话记忆。批准的粒度应按"Server 加工具定义哈希"记录,工具定义变化后旧批准失效,否则恶意 Server 可以先发布只读工具获取批准,再把它替换为写操作。
工具投毒(tool poisoning)指 Server 在工具说明、参数说明或工具结果中写入面向模型的指令,使模型把不可信文本当作任务要求执行。这类攻击不依赖协议漏洞,只依赖模型会把上下文中的文本当作指令。缓解手段包括:把工具元数据视为不可信输入并在界面中展示原文;对工具定义做哈希固定,变化时重新审批;限制可安装的 Server 来源;对工具结果中的指令性文本做分隔与过滤。
混淆代理(confused deputy)指 Server 持有比调用者更大的权限,攻击者通过它代理执行越权操作。典型情形是 Server 内置了高权限服务账号,调用者只需构造参数即可访问无权访问的数据。缓解要求每个请求都携带调用者身份并在 Server 内做授权判断,不能因为"请求来自宿主"就默认可信。
令牌透传(token passthrough)指 Server 把收到的访问令牌原样转发给下游 API。MCP 规范明确禁止这种行为:Server 不得接受未签发给自己的令牌,必须校验令牌的受众,否则被攻破的下游服务可以用该令牌横向访问其他资源。HTTP 传输的授权基于 OAuth 2.1,令牌应带资源指示符。
跨 Server 的提示注入传播是 MCP 特有的风险。Server A 的工具结果可以包含"请调用 Server B 并把配置发送到某地址",若 Host 自动把 A 的输出作为 B 的调用参数,用户同意就被绕过。缓解要求:不同信任域的 Server 之间不自动串联;对跨 Server 的数据流打标签;调用 B 时重新请求同意;限制 B 能看到的上下文范围。
还有两类与部署相关的风险。命名遮蔽指多个 Server 提供同名工具,Host 未做命名空间隔离,模型调用了非预期的实现。本地 Server 即任意代码执行:stdio Server 以用户权限运行,可读取文件与环境变量,安装一个 Server 等同于授予其与用户同等的权限,应在容器或受限账户中运行并清理环境变量。
12 与 OpenAI function calling 的关系
两者不在同一层。函数调用是模型 API 的输出格式约定:调用方在每次请求中传入工具定义,模型输出工具名与参数,执行发生在调用方进程内,没有标准的发现机制与生命周期。MCP 是进程间协议:工具定义在运行时通过 tools/list 获取,执行发生在独立进程或远程服务,结果以内容块返回,连接有版本协商、能力声明与取消语义。
| 维度 | OpenAI function calling | MCP |
|---|---|---|
| 抽象层 | 模型输出格式 | 应用层协议 |
| 工具定义来源 | 每次请求的 tools 参数 | tools/list 运行时获取 |
| 发现时机 | 调用前由应用确定 | 握手后动态获取,可变更 |
| 执行位置 | 调用方进程 | 独立进程或远程服务 |
| 传输 | HTTP API | stdio 或 HTTP |
| 认证 | API 密钥 | 进程权限或 OAuth 2.1 |
| 错误通道 | 工具消息回填 | JSON-RPC error 与 isError 两种 |
| 多来源 | 应用自行聚合 | Host 聚合多个 Client |
二者的组合方式是上下游关系。Host 把 tools/list 的结果转换为模型 API 的 tools 参数,把模型返回的调用意图转换为 tools/call。转换时需要注意模式方言差异:函数调用的严格模式通常要求对象模式声明 additionalProperties: false、所有属性列入 required、可选字段用联合类型表达 null,而 MCP 的 inputSchema 是完整的 JSON Schema,直接透传可能被模型 API 拒绝。转换层必须做子集裁剪与校验,且裁剪后的模式要与 Server 端的校验保持一致,否则会出现"模型生成的参数被 API 接受但被 Server 拒绝"的错位。
关键直觉
机制性表述
MCP 把能力发现与能力调用固定为
tools/list与tools/call两类消息,因此 Host 在编译期不需要知道任何 Server 的存在;握手完成后,Server 的能力集合成为一个可枚举的运行时对象,Host 对它的处理与本地函数表相同。协议保证的是消息形状、状态迁移与错误通道,不保证能力语义,语义仍由每个 Server 的模式与文档定义。与定义的关系:定义中的"统一的消息格式"对应这三类消息与内容块,"能力协商"对应
initialize的capabilities字段,"权限边界"对应 Host 作为唯一同时看见模型输出与全部连接的位置。由此可以推出,所有跨 Server 的安全决策只能在 Host 完成,Server 只能约束自己的输出。
例子与代码
例 1:最小 MCP server
下面是一个完整的 stdio Server,只依赖 Python 标准库,实现 initialize、tools/list、tools/call 三个方法与 notifications/initialized 通知。环境为 Python 3.10 及以上,实测 3.12。
#!/usr/bin/env python3
"""最小 MCP server(Python 3.10+,仅标准库):stdio 传输,暴露一个 add 工具。"""
import json
import sys
PROTOCOL_VERSION = "2025-06-18"
SERVER_INFO = {"name": "minimal-adder", "version": "0.1.0"}
TOOLS = [
{
"name": "add",
"title": "两数相加",
"description": "返回两个数字 a 与 b 的和,结果绝对值不得超过 1000。",
"inputSchema": {
"type": "object",
"properties": {"a": {"type": "number"}, "b": {"type": "number"}},
"required": ["a", "b"],
"additionalProperties": False,
},
"annotations": {"readOnlyHint": True, "destructiveHint": False,
"idempotentHint": True, "openWorldHint": False},
}
]
def log(text):
"""日志写入 stderr;stdout 由协议独占。"""
print(f"[minimal-adder] {text}", file=sys.stderr, flush=True)
def response(req_id, result):
return {"jsonrpc": "2.0", "id": req_id, "result": result}
def error(req_id, code, message):
return {"jsonrpc": "2.0", "id": req_id, "error": {"code": code, "message": message}}
def run_add(arguments):
"""执行工具;参数类型错误抛 ValueError,业务限制用 isError 返回。"""
values = {}
for name in ("a", "b"):
value = arguments.get(name)
if isinstance(value, bool) or not isinstance(value, (int, float)):
raise ValueError(f"参数 {name} 必须是数字")
values[name] = value
total = values["a"] + values["b"]
if abs(total) > 1000:
return {"content": [{"type": "text", "text": f"结果 {total} 超出上限 1000"}],
"isError": True}
return {"content": [{"type": "text", "text": json.dumps({"sum": total})}],
"structuredContent": {"sum": total},
"isError": False}
def handle(message, state):
"""处理一条 JSON-RPC 消息,返回待写出的消息列表。"""
method = message.get("method")
req_id = message.get("id")
if "id" not in message: # 通知:不产生响应
if method == "notifications/initialized":
state["initialized"] = True
log("会话就绪")
return []
if method == "initialize":
return [response(req_id, {
"protocolVersion": PROTOCOL_VERSION,
"capabilities": {"tools": {"listChanged": False}},
"serverInfo": SERVER_INFO,
"instructions": "使用 add 计算两数之和。",
})]
if method == "ping":
return [response(req_id, {})]
if not state["initialized"]:
return [error(req_id, -32600, "请求必须在 initialized 通知之后发送")]
if method == "tools/list":
return [response(req_id, {"tools": TOOLS})]
if method == "tools/call":
params = message.get("params") or {}
if params.get("name") != "add":
return [error(req_id, -32602, f"未知工具:{params.get('name')}")]
try:
return [response(req_id, run_add(params.get("arguments") or {}))]
except ValueError as exc: # 参数不符合模式:协议层错误
return [error(req_id, -32602, str(exc))]
return [error(req_id, -32601, f"方法不存在:{method}")]
def main():
# stdio 传输固定 UTF-8;Windows 默认使用本地代码页,不显式设置会解码失败。
sys.stdin.reconfigure(encoding="utf-8")
sys.stdout.reconfigure(encoding="utf-8", newline="\n")
sys.stderr.reconfigure(encoding="utf-8")
state = {"initialized": False}
log(f"启动,协议版本 {PROTOCOL_VERSION}")
while True:
line = sys.stdin.readline()
if not line: # stdin 关闭:宿主结束会话
break
line = line.strip()
if not line:
continue
try:
message = json.loads(line)
except json.JSONDecodeError:
sys.stdout.write(json.dumps(
{"jsonrpc": "2.0", "id": None,
"error": {"code": -32700, "message": "JSON 解析失败"}},
ensure_ascii=False) + "\n")
sys.stdout.flush()
continue
for outgoing in handle(message, state):
sys.stdout.write(json.dumps(outgoing, ensure_ascii=False) + "\n")
sys.stdout.flush() # 每条响应后立即刷新
log("stdin 关闭,退出")
if __name__ == "__main__":
main()
逐行解释如下,行号与上列代码块一致。
| 行号 | 代码 | 作用 |
|---|---|---|
| 1–2 | 文件头与模块说明 | 声明用途与依赖,不参与协议 |
| 4–5 | import json, sys | 只用标准库,避免宿主安装第三方包 |
| 7–8 | PROTOCOL_VERSION、SERVER_INFO | 版本与身份,initialize 结果使用 |
| 10–24 | TOOLS | 工具清单,tools/list 原样返回,不在每次调用时重建 |
| 27–29 | log | 日志固定写 stderr,flush=True 保证崩溃前日志落盘 |
| 32–37 | response、error | 封装 result 与 error 两种互斥响应,避免手写 jsonrpc 字段 |
| 40–54 | run_add | 类型校验与结果构造;类型错误抛异常,业务限制走 isError |
| 45–46 | 类型校验 | 布尔值是 int 子类,必须先排除;不合法抛 ValueError |
| 49–51 | 业务限制 | 结果超出上限属于执行失败,走结果通道 |
| 52–54 | 成功结果 | 同时返回文本与 structuredContent,兼容只读文本的客户端 |
| 57–65 | 通知分支 | 先判断 id 是否存在,通知不产生任何响应 |
| 62–64 | initialized 处理 | 记录会话状态,初始化检查在此通过 |
| 67–73 | initialize | 返回版本、能力、身份与说明;能力只声明 tools |
| 75–76 | ping | 返回空结果,探活可用 |
| 78–79 | 初始化检查 | 握手前请求返回 -32600,阻止未协商即调用 |
| 81–82 | tools/list | 返回静态清单,无分页 |
| 84–91 | tools/call | 未知工具与参数错误都返回 -32602 |
| 86–87 | 未知工具 | 工具名不匹配,协议层错误 |
| 88–91 | 参数异常转换 | ValueError 转为 -32602,模型无法据此修正 |
| 93 | 兜底 | 未实现方法返回 -32601 |
| 96–102 | main 初始化 | 三处 reconfigure 固定 UTF-8 与换行 |
| 98–100 | 编码设置 | Windows 默认代码页为 GBK,不设置会在父进程解码时报错 |
| 103–109 | 读循环 | 用 readline 逐行读取;EOF 表示宿主关闭会话 |
| 110–118 | 解析失败 | 返回 -32700,此时 id 未知,置为 null |
| 119–121 | 写出与刷新 | 每条响应后 flush,否则父进程会阻塞等待 |
| 122 | 退出日志 | 记录正常关闭,便于区分崩溃 |
| 125–126 | 入口 | 仅在直接运行时启动,便于导入测试 |
三个设计点需要强调。第一,stdout 只写协议消息,任何 print 调试语句都会破坏 JSON-RPC 帧,因此 log 固定写 stderr。第二,业务错误与协议错误分开,前者让模型看到原因,后者让 Host 判断集成是否正确。第三,刷新与编码必须显式设置,缓冲与代码页是 stdio 传输最常见的两个故障源。
例 2:最小 client 的请求序列
下面的 Client 启动上例的 Server,依次发送 initialize、notifications/initialized、tools/list 与三次 tools/call,并在结束时关闭标准输入。
#!/usr/bin/env python3
"""最小 MCP client(仅标准库):启动 server,按顺序发送四类消息。"""
import json
import subprocess
import sys
SERVER = [sys.executable, "mcp_server.py"]
class Client:
def __init__(self, command):
self.proc = subprocess.Popen(command, stdin=subprocess.PIPE,
stdout=subprocess.PIPE, text=True,
encoding="utf-8", bufsize=1)
self.next_id = 1
def send(self, payload):
self.proc.stdin.write(json.dumps(payload, ensure_ascii=False) + "\n")
self.proc.stdin.flush() # 不刷新则 server 收不到
def request(self, method, params=None):
req_id = self.next_id
self.next_id += 1
payload = {"jsonrpc": "2.0", "id": req_id, "method": method}
if params is not None:
payload["params"] = params
self.send(payload)
while True: # 按 id 匹配响应,跳过不相关消息
line = self.proc.stdout.readline()
if not line:
raise RuntimeError("server 已关闭")
message = json.loads(line)
if message.get("id") == req_id:
return message
def notify(self, method):
self.send({"jsonrpc": "2.0", "method": method})
client = Client(SERVER)
init = client.request("initialize", {
"protocolVersion": "2025-06-18",
"capabilities": {"roots": {"listChanged": True}},
"clientInfo": {"name": "minimal-client", "version": "0.1.0"},
})
print("initialize ->", json.dumps(init["result"], ensure_ascii=False))
client.notify("notifications/initialized")
tools = client.request("tools/list")
print("tools/list ->", json.dumps(tools["result"], ensure_ascii=False))
call = client.request("tools/call", {"name": "add", "arguments": {"a": 19, "b": 23}})
print("tools/call ->", json.dumps(call["result"], ensure_ascii=False))
big = client.request("tools/call", {"name": "add", "arguments": {"a": 900, "b": 200}})
print("超上限 ->", json.dumps(big["result"], ensure_ascii=False))
bad = client.request("tools/call", {"name": "add", "arguments": {"a": "19", "b": 23}})
print("坏参数 ->", json.dumps(bad["error"], ensure_ascii=False))
unknown = client.request("tools/call", {"name": "sub", "arguments": {}})
print("未知工具 ->", json.dumps(unknown["error"], ensure_ascii=False))
client.proc.stdin.close()
client.proc.wait(timeout=5)
运行 python mcp_client.py,输出如下。
initialize -> {"protocolVersion": "2025-06-18", "capabilities": {"tools": {"listChanged": false}}, "serverInfo": {"name": "minimal-adder", "version": "0.1.0"}, "instructions": "使用 add 计算两数之和。"}
tools/list -> {"tools": [{"name": "add", "title": "两数相加", "description": "返回两个数字 a 与 b 的和,结果绝对值不得超过 1000。", "inputSchema": {"type": "object", "properties": {"a": {"type": "number"}, "b": {"type": "number"}}, "required": ["a", "b"], "additionalProperties": false}, "annotations": {"readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false}}]}
tools/call -> {"content": [{"type": "text", "text": "{\"sum\": 42}"}], "structuredContent": {"sum": 42}, "isError": false}
超上限 -> {"content": [{"type": "text", "text": "结果 1100 超出上限 1000"}], "isError": true}
坏参数 -> {"code": -32602, "message": "参数 a 必须是数字"}
未知工具 -> {"code": -32602, "message": "未知工具:sub"}
对应的线上消息序列为七条。第 3 条是通知,没有响应;第 4 条与第 6 条是客户端在收到上一条响应后继续发出的请求。
1 C→S {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}
2 S→C {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18",...}}
3 C→S {"jsonrpc":"2.0","method":"notifications/initialized"}
4 C→S {"jsonrpc":"2.0","id":2,"method":"tools/list"}
5 S→C {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
6 C→S {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add",...}}
7 S→C {"jsonrpc":"2.0","id":3,"result":{"content":[...],"isError":false}}
request 中的循环是必要的:连接上可能先到服务端发起的请求或日志通知,按 id 过滤可以跳过它们。用固定 sleep 等待响应不可靠,因为延迟随负载变化;正确做法是阻塞读取直到匹配的 id 出现,并在需要超时时改用 select 或独立线程计时,不能靠猜测延迟。client.proc.stdin.close() 触发 Server 的 EOF 分支,wait(timeout=5) 保证不留下孤儿进程;去掉这两行,子进程会一直等待输入。
错误示例印证第 5 节的两个通道:坏参数与未知工具都返回 error 且码为 -32602,因为参数不符合 inputSchema、工具名不存在属于协议层错误,模型无法通过重试修正;超上限返回 result 且 isError 为真,因为工具已经执行并判定结果违反业务规则,模型可以据此调整参数。前者应由 Host 修正调用或记录集成缺陷,后者应原样回填给模型。
易错点
以下六条均可在运行结果或日志中直接检验。
1. 把日志或调试输出写入标准输出。
2. 未初始化即调用,或重复初始化。握手前发送
tools/list会得到-32600或被直接断开;客户端在initialize响应到达前发送initialized通知,会让服务端在版本未定的情况下进入就绪状态。3. 模式类型与实际值不一致。
"type": "integer"在 Python 中会接受True,因为布尔值是整数的子类;"type": "number"不接受字符串"19",但很多客户端会把表单输入当字符串发送。校验必须在 Host 与 Server 两侧都做,且先排除布尔值。4. 超时后既不取消也不释放映射。Host 超时后直接丢弃请求,Server 继续执行并最终写回响应,该响应的
id已不在映射表中,可能被误配给新请求;正确做法是发送notifications/cancelled、保留id直到收到响应或会话结束、并标记迟到响应。5. 忽略 stdio 的缓冲与编码。父进程写入后不刷新,Server 永远收不到请求;Server 不刷新,Client 阻塞在读取;Windows 上不把三个流设为 UTF-8,中文内容会以本地代码页编码,父进程按 UTF-8 解码时报
UnicodeDecodeError。6. 把能力声明或
annotations当作保证。声明tools不代表每次调用成功;readOnlyHint只是提示,恶意 Server 可以标注只读却执行写操作。Host 必须独立判断风险,不能把提示字段作为权限依据。
关联笔记
- 前置 AI-Agent与工具调用:工具的三元组、调用意图与结果回填是该篇的主体,本篇把这些对象提升为跨进程协议。
- 前置 结构化输出:
inputSchema与outputSchema的语义、必填性与additionalProperties规则来自 JSON Schema,该篇第 2 节给出了关键字的完整对照。 - 后续 Harness与Loop工程:Host 把 Client 当作工具执行层的一个后端,循环、预算、重试与轨迹在该篇展开;本篇的错误分层对应其错误分类表。
- 后续 Agent工作流与编排:多 Server 的路由、信任域划分与审批策略属于编排层,本篇只提供连接与能力模型。
- 对照 RAG原理与流程:资源是应用推送上下文,检索是系统按查询拉取上下文,两者的注入风险相同而触发时机不同。
达标检测
- [ ] 写出 个宿主与 个提供者的适配器数量对比,并说明协议化减少了哪一部分工作量、没有减少哪一部分。
- [ ] 给出
initialize的请求与响应字段,说明版本协商在客户端不支持服务端版本时的正确行为。 - [ ] 判断下列三种失败分别属于哪一层并给出返回方式:工具名不存在、参数
a为字符串、下游数据库连接超时。 - [ ] 实现一个 stdio Server,提供
echo工具,并验证在握手前发送tools/call会得到-32600。 - [ ] 写出一次带取消的工具调用时序,说明接收方在收到
notifications/cancelled后是否应发送响应。 - [ ] 列出工具投毒、令牌透传、跨 Server 注入三种风险的触发条件与至少一条缓解措施。
- [ ] 把本篇
add工具的inputSchema转换为函数调用严格模式可接受的模式,指出需要修改的字段。
参考来源
- Model Context Protocol 规范,modelcontextprotocol.io,
2025-06-18版 —— 对应第 2 至第 10 节的传输、消息、握手、三类原语、取消与错误码。 - Anthropic, "Introducing the Model Context Protocol", 2024 —— 对应第 1 节的角色划分与第 5 节的工具设计动机。
- JSON-RPC 2.0 Specification,jsonrpc.org —— 对应第 3 节的请求、响应、通知与错误对象规则。
- Claude Desktop 文档 —— 对应第 1 节 Host 的实际形态与第 11 节的用户同意流程。
- MCP Security Best Practices,modelcontextprotocol.io —— 对应第 11 节的混淆代理、令牌透传、会话劫持与本地 Server 风险。