Skip to content
Lv4MCP 协议进度 2 / 6

第 2 章:协议骨架:JSON-RPC、握手与能力协商 ​

MCP 没有发明新协议,它用的是 2005 年就存在的 JSON-RPC 2.0。所有"新东西"都在消息语义里。


学习目标 ​

  • 认出 JSON-RPC 的三种消息:请求、响应、通知
  • 走一遍 initialize 握手,知道双方各自声明什么
  • 看懂一次 tools/call 的完整往返
  • 分清"协议错误"和"工具执行失败"

2.1 JSON-RPC 2.0 的三种消息 ​

json
// 请求:一定有 id
{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}

// 响应:id 必须和请求一致
{"jsonrpc": "2.0", "id": 1, "result": {"tools": [ ... ]}}

// 通知:没有 id,不期待响应
{"jsonrpc": "2.0", "method": "notifications/initialized"}

三条规则决定了实现方式:

  1. id 是关联键。一条连接上可以并发多个请求,靠 id 把响应配回请求;
  2. 通知不占 id,也不会收到响应——发出去就是发出去;
  3. method 是字符串,MCP 用自己的命名空间(tools/list、resources/read 等)。
同一条连接上,三种消息混着跑请求(有 id){"jsonrpc":"2.0","id":7,"method":"tools/call",…}响应(同 id 回){"jsonrpc":"2.0","id":7,"result":{…}}通知(无 id){"jsonrpc":"2.0","method":"notifications/…"}错误响应{"id":7,"error":{"code":-32601,"message":…}}这就是"协议骨架"的全部:一个 id 关联、一个 method 分发、一个 error 结构。MCP 的所有能力(工具、资源、提示词)都是在这三条规则上"加语义"。transport(stdio / HTTP)只决定这些 JSON 怎么传输,不改消息本身。

2.2 握手:initialize ​

连上之后,第一件事不是问工具,是互相介绍。

请求长这样:

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "my-agent", "version": "1.0.0" }
  }
}

响应:

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": {}, "resources": {} },
    "serverInfo": { "name": "filesystem", "version": "0.3.1" }
  }
}

protocolVersion 是日期字符串,具体取哪个值以官方规范为准。双方不一致时,由客户端决定是否继续。

为什么必须先握手?因为后面的行为取决于"对方支持什么"。没协商就发 resources/read,可能直接收到 -32601。


2.3 能力协商:谁声明什么 ​

方向能力含义
Server → Clienttools我提供可被调用的工具
Server → Clientresources我提供可读的资源(URI 标识)
Server → Clientprompts我提供可选的提示词模板
Client → Serversampling我允许你在需要时请求模型生成
Client → Serverroots我告诉你我的文件系统边界在哪
Client → Serverelicitation我允许你向我索取补充信息

两条实践结论:

  • 能力是"我支持",不是"我一定用"。声明了 tools,不代表每次都要调;
  • 客户端能力决定 server 能做什么。server 想"让模型帮我总结",前提是 client 声明了 sampling,否则只能自己算或报错。

2.4 一次 tools/call 的完整往返 ​

两个容易忽略的点:

  1. tools/list 可能分页。工具很多时返回 nextCursor,客户端要循环拉完,别只拉第一页就当全集;
  2. tools/call 的参数是 JSON Schema 校验过的。schema 写错(比如 required 漏了字段),模型给不出合法参数,调用会一直失败。

2.5 两种"错误",别混 ​

类型出现在例子谁来处理
协议错误error 字段-32601 方法不存在、-32602 参数不合法客户端修代码
工具执行失败result 里 isError: true文件不存在、数据库超时交给模型,让它解释或换方案
json
// 协议错误:连方法都不对
{"jsonrpc":"2.0","id":9,"error":{"code":-32601,"message":"Method not found"}}

// 工具失败:协议没问题,是业务失败
{"jsonrpc":"2.0","id":9,"result":{"content":[{"type":"text","text":"文件不存在:README.md"}],"isError":true}}

这个区分很关键:协议错误应该由客户端修,工具失败应该让模型看到(它可能换个路径再试)。把业务失败包装成协议错误,会让模型失去"重试"的机会。

常用错误码(JSON-RPC 标准):

code含义
-32700解析失败(JSON 都不合法)
-32600请求不合法
-32601方法不存在
-32602参数不合法
-32603内部错误
-32000 ~ -32099服务端自定义

2.6 生命周期与终止 ​

initialize → notifications/initialized → 正常操作(任意多次) → 关闭
  • 关闭方式取决于传输:stdio 是关管道,HTTP 是断连接;
  • 不要在握手前发业务请求,也不要在关闭后继续发通知;
  • 长连接要处理"对端突然消失"——stdio 读不到 EOF 就卡住的实现很常见。

2.7 一张速查 ​

你想做的事发什么
建立连接initialize → 收结果 → notifications/initialized
看看有哪些工具tools/list(注意 nextCursor)
调用工具tools/call(name + arguments)
列资源resources/list + resources/templates/list
读资源resources/read(URI)
要提示词模板prompts/list / prompts/get

本章小结 ​

要点说明
协议JSON-RPC 2.0,请求/响应/通知三态
id关联请求与响应,通知没有 id
握手initialize 交换版本与能力,再发 notifications/initialized
能力server 声明 tools/resources/prompts;client 声明 sampling/roots/elicitation
调用tools/list → 转 FC → tools/call → 结果回模型
分页工具多时有 nextCursor,要拉完
错误协议错误走 error,业务失败走 isError

下一章 ​

三个原语:工具、资源、提示词,各自解决什么、什么时候别用错。

本文阅读--次|全站访问--次|访客--人