w wyl123ly 的博客
MD

MCP协议

46 KB 2026.10.18 原文件

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 传输有两代,差异在端点数量与会话标识。下表对比三者。

维度stdioHTTP+SSE(2024-11-05)Streamable HTTP(2025-03-26 起)
端点子进程的 stdin/stdout两个:GET 事件流端点与 POST 消息端点一个:POST 与 GET 使用同一 URL
客户端到服务端写入 stdin,每行一条 JSONPOST 到消息端点,返回 202POST 单条消息,响应为 JSON 或 SSE
服务端到客户端写入 stdoutGET 建立的 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 收到后必须重新枚举。

方向能力附加字段对应方法与通知
ClientrootslistChangedroots/list、notifications/roots/list_changed
Clientsampling无sampling/createMessage
Clientelicitation无elicitation/create
ServertoolslistChangedtools/list、tools/call、notifications/tools/list_changed
Serverresourcessubscribe、listChangedresources/list、resources/templates/list、resources/read、resources/subscribe
ServerpromptslistChangedprompts/list、prompts/get、notifications/prompts/list_changed
Serverlogging无logging/setLevel、notifications/message
Servercompletions无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必填字段用途
texttext纯文本结果
imagedata、mimeTypebase64 编码图像
audiodata、mimeTypebase64 编码音频
resource_linkuri、name引用资源,不内联内容
resourceresource 对象,含 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/listtools/call是
资源应用resources/list、resources/templates/listresources/read由应用决定
提示模板用户prompts/listprompts/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 使用的错误码如下表。

码名称触发条件
-32700Parse error收到非 JSON 文本
-32600Invalid Request缺少必需字段、id 非法、消息不是合法请求
-32601Method not found方法未实现
-32602Invalid params参数不符合模式、工具名不存在
-32603Internal error服务端内部异常
-32002Resource not foundresources/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 callingMCP
抽象层模型输出格式应用层协议
工具定义来源每次请求的 tools 参数tools/list 运行时获取
发现时机调用前由应用确定握手后动态获取,可变更
执行位置调用方进程独立进程或远程服务
传输HTTP APIstdio 或 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–5import json, sys只用标准库,避免宿主安装第三方包
7–8PROTOCOL_VERSION、SERVER_INFO版本与身份,initialize 结果使用
10–24TOOLS工具清单,tools/list 原样返回,不在每次调用时重建
27–29log日志固定写 stderr,flush=True 保证崩溃前日志落盘
32–37response、error封装 result 与 error 两种互斥响应,避免手写 jsonrpc 字段
40–54run_add类型校验与结果构造;类型错误抛异常,业务限制走 isError
45–46类型校验布尔值是 int 子类,必须先排除;不合法抛 ValueError
49–51业务限制结果超出上限属于执行失败,走结果通道
52–54成功结果同时返回文本与 structuredContent,兼容只读文本的客户端
57–65通知分支先判断 id 是否存在,通知不产生任何响应
62–64initialized 处理记录会话状态,初始化检查在此通过
67–73initialize返回版本、能力、身份与说明;能力只声明 tools
75–76ping返回空结果,探活可用
78–79初始化检查握手前请求返回 -32600,阻止未协商即调用
81–82tools/list返回静态清单,无分页
84–91tools/call未知工具与参数错误都返回 -32602
86–87未知工具工具名不匹配,协议层错误
88–91参数异常转换ValueError 转为 -32602,模型无法据此修正
93兜底未实现方法返回 -32601
96–102main 初始化三处 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. 把日志或调试输出写入标准输出。print 一行就会在 JSON 流中插入非 JSON 文本,客户端在无关字节处报解析错误;日志必须走标准错误,并在每条响应后刷新标准输出。

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 风险。