第 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"}三条规则决定了实现方式:
id是关联键。一条连接上可以并发多个请求,靠 id 把响应配回请求;- 通知不占 id,也不会收到响应——发出去就是发出去;
- method 是字符串,MCP 用自己的命名空间(
tools/list、resources/read等)。
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 → Client | tools | 我提供可被调用的工具 |
| Server → Client | resources | 我提供可读的资源(URI 标识) |
| Server → Client | prompts | 我提供可选的提示词模板 |
| Client → Server | sampling | 我允许你在需要时请求模型生成 |
| Client → Server | roots | 我告诉你我的文件系统边界在哪 |
| Client → Server | elicitation | 我允许你向我索取补充信息 |
两条实践结论:
- 能力是"我支持",不是"我一定用"。声明了
tools,不代表每次都要调; - 客户端能力决定 server 能做什么。server 想"让模型帮我总结",前提是 client 声明了
sampling,否则只能自己算或报错。
2.4 一次 tools/call 的完整往返
两个容易忽略的点:
tools/list可能分页。工具很多时返回nextCursor,客户端要循环拉完,别只拉第一页就当全集;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 |
下一章
三个原语:工具、资源、提示词,各自解决什么、什么时候别用错。