调用远程服务有两种风格。REST 把一切建模成资源,用 URL 定位、用 HTTP 动词操作;另一派把远程调用建模成"函数调用"——客户端发一个方法名加参数,服务端返回结果——这就是 RPC。JSON-RPC 是 RPC 里最轻的一派:不依赖任何框架、不规定传输层、整个协议就是两个 JSON 对象的往返。它也是 MCP 协议 的传输层底座——agent 生态里工具调用的每一行报文,写的都是 JSON-RPC。
本文解剖它的请求、响应、错误、通知与批量五样东西,最后看 MCP 怎么用它。规范全文见 jsonrpc.org/specification,2.0 版 2009 年定稿,至今未改——这是一门足够小、也足够稳定的协议。
1、RPC 解决什么问题
程序员最熟悉的调用形态是函数:subtract(42, 23),进去参数、出来结果。RPC(远程过程调用)把这个形态延伸到网络上:调用的函数跑在另一台机器,中间的序列化、传输、寻址全部被协议藏起来。JSON-RPC 用 JSON 当序列化层,把"调函数"压缩到极简,与 REST 的取向对比如下:
| 维度 | REST | JSON-RPC |
|---|---|---|
| 建模方式 | 资源与状态转移 | 方法调用 |
| 报文载体 | URL 路径加 HTTP 动词 | 一个 JSON 对象 |
| 传输绑定 | HTTP | 无所谓,HTTP、WebSocket、stdio 都行 |
| 典型场景 | 开放 API、资源管理 | 内部接口、进程间协议 |
表里的"传输无所谓"是它被 MCP 选中的直接原因:本地工具走标准输入输出、远程数据源走 HTTP,报文格式可以是同一套。
2、请求与响应解剖
2.1、请求对象
一次调用就是一个 JSON 对象,四个成员各司其职:
| 成员 | 类型 | 必填 | 职责 |
|---|---|---|---|
| jsonrpc | 字符串 | 是 | 固定 "2.0",声明协议版本 |
| method | 字符串 | 是 | 要调用的方法名 |
| params | 数组或对象 | 否 | 参数,两种形态皆可 |
| id | 字符串或数字 | 否 | 请求编号,响应原样带回 |
同一减法调用,参数的两种写法如下:
{"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
{"jsonrpc": "2.0", "method": "subtract",
"params": {"subtrahend": 23, "minuend": 42}, "id": 2}
前者按位置传参(数组下标即形参序),后者按名传参(键即形参名);两种等价,服务端按声明支持其一。id 是关联请求与响应的唯一凭据——并发发出十个请求,靠它把应答对号入座。
2.2、响应对象
服务端返回同样极简的对象:jsonrpc、id 原样带回,再加上 result 与 error 二选一。成功的应答长这样:
{"jsonrpc": "2.0", "id": 1, "result": 19}
两条硬规则:其一,result 与 error 必须且只能出现一个——成功就给 result(哪怕值是 null),失败就给 error,不存在同时出现或同时缺席;其二,id 必须与请求一致,服务端连请求都解析不出来时才允许回 null。
3、错误对象与错误码
失败时的 error 是一个对象,三个成员:code 整型错误码、message 一句话描述、data 可选的补充细节。规范预定义的错误码如下:
| 错误码 | 含义 | 触发场景 |
|---|---|---|
| -32700 | 解析错误 | 报文不是合法 JSON |
| -32600 | 无效请求 | 缺成员、版本不是 "2.0" |
| -32601 | 方法不存在 | method 名字对不上 |
| -32602 | 无效参数 | 参数类型或形态不符 |
| -32603 | 内部错误 | 服务端自身异常 |
| -32000 到 -32099 | 服务端错误 | 保留给实现自定义 |
错误应答的完整形态如下:
{"jsonrpc": "2.0", "id": 1,
"error": {"code": -32601, "message": "Method not found"}}
表里的分段有讲究:-32700 到 -32603 是协议层错误,各服务端语义一致;-32000 段留给业务自定义——写自己的服务时,业务错误码从这段里取,别占用协议段。
4、通知与批量
通知是省掉 id 的请求:客户端只发不收,服务端不得回复——哪怕处理出错也不回。它适合"顺带告知"的场景,比如状态上报:
{"jsonrpc": "2.0", "method": "progress", "params": {"done": 3, "total": 10}}
这条报文没有 id,服务端处理完悄然无声——调用方也无法知道它成功与否,这正是通知与请求的本质区别。批量则把多个请求装进一个数组一次发出:服务端逐个独立处理,应答也装成数组回来,顺序与请求不必对应,靠各自的 id 关联。两条边界规则:全是通知的批量不产生任何应答;空数组直接返回一个"无效请求"错误。
5、MCP 的传输层
MCP 之所以选 JSON-RPC,是因为它的会话恰好需要三种报文形态:请求要应答(列工具、调工具)、通知只单向(取消、进度),偶尔还要批量——JSON-RPC 一个协议全覆盖。MCP 的握手与工具调用,报文就是标准的 JSON-RPC 方法:
{"jsonrpc": "2.0", "method": "tools/call", "id": 7,
"params": {"name": "query_orders",
"arguments": {"user_id": "u123"}}}
方法名换成带命名空间的 tools/call,其余成员原封不动——MCP 在 JSON-RPC 之上只加了语义约定,没有改协议本身。一次 host 与 server 的往返如下:
图中"带 id 的请求等 result、无 id 的通知不等回复"两条线交替,正是第 4 节两样机制在真实协议里的用法。MCP 的报文细则见官方规范与 GitHub 组织。
6、实践要点
四条来自实战的注意。其一,版本必须是字符串 "2.0":写成数字 2.0 会被判无效请求——这个字段是给未来版本预留的,不是装饰。其二,id 别用浮点数:规范明确不建议,小数在异构语言间可能丢精度,用整数或字符串最稳。其三,传输层自选但语义不变:HTTP 下就是一次 POST 加 Content-Type: application/json,WebSocket 下可以多路复用,stdio 下逐行读写——协议对载体零要求,这正是它能同时服务本地工具与远程服务的原因。其四,通知不保证送达:无应答意味着无确认,重要操作永远用带 id 的请求。
7、总结
回顾全文:JSON-RPC 把远程调用压缩成请求响应两个 JSON 对象,四个成员的请求、result 与 error 二选一的应答、六个预定义错误码、无 id 即通知、数组即批量;MCP 在它之上只加命名空间与语义,agent 工具调用的报文层就此统一。对于要接 MCP 或自建轻量接口的开发者,建议把第 2 节的两个对象手写一遍——协议小到半小时可通读规范全文,而"传输无关"的设计智慧,值得在任何协议设计里偷师。


