MCP 通信消息格式之 JSON-RPC 2.0 协议

一、背景介绍

MCP 中 Client 与 Server 间使用 JSON-RPC 2.0 作为通信消息格式。JSON-RPC 是 RPC（远程过程调用）的一种具体实现，RPC 是一种通信范式，其核心目标是屏蔽网络细节，使远程调用如同本地调用般简单，并可基于多种底层网络协议（如 TCP/HTTP）实现。常见的 RPC 框架有 gRPC、Dubbo 和 Thrift。

JSON-RPC 2.0 是一种使用 JSON 格式的轻量级远程过程调用 (RPC) 协议，与 RPC 有以下区别：

特性	RPC（通用）	JSON-RPC
协议类型	抽象概念，有多种实现	RPC 的一种具体实现
数据格式	二进制（如 Protobuf）、文本等	默认使用 JSON
传输协议	任意（TCP/HTTP/UDP 等）	通常基于 HTTP/HTTPS 或 WebSocket
跨语言兼容性	依赖具体实现（如 gRPC）	天然支持（JSON 是通用标准）
性能	二进制协议通常更高	文本协议，性能较低
使用场景	高性能内部服务（如 gRPC）	Web API、前后端交互、脚本语言

二、消息类型

1. 请求（Request）

{
  "jsonrpc": "2.0",
  "method": "方法名",
  "params": {"参数名": "值"} | ["值 1", "值 2"],  // 对象或数组
  "id": "唯一ID"                             // 可选（通知请求可省略）
}

jsonrpc : 必须为 "2.0"。

method: 调用的方法名（字符串）。

params: 参数（可省略），支持对象（命名参数）或数组（位置参数）。

id: 请求标识符。

2. 响应（Response）

成功响应：

{
  "jsonrpc": "2.0",
  "result": "返回值",
  "id": "对应请求 ID"
}

错误响应：

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": "额外错误信息"  // 可选
  },
  "id": "对应请求 ID"      // 若请求无 ID，则为 null
}

标准错误码：

Code	Message	说明
-32700	Parse error	JSON 解析失败
-32600	Invalid Request	请求格式不符合规范
-32601	Method not found	方法不存在
-32602	Invalid params	参数无效
-32603	Internal error	服务端内部错误
-32000	Server error（自定义）	业务级错误（范围：-32000 至 -32099）

3. 通知（Notification）

无 id 的请求，客户端不返回响应：

{
  "jsonrpc": "2.0",
  "method": "log_event",
  "params": {"event": "user_login"}
}

三、主要特点

（1）简单轻量：协议设计简洁，消息格式简单。

（2）语言无关：基于 JSON，几乎所有编程语言都支持。

（3）传输层无关：可在 HTTP、WebSocket、TCP 等多种传输协议上使用。

（4）支持通知（不需要响应的请求）。

（5）支持批量请求。

四、使用建议

1. 请求与响应设计

（1）严格校验 jsonrpc 字段：确保值为 "2.0"，避免版本混淆。

（2）明确参数类型：在文档中声明 params 是对象还是数组。

（3）处理通知请求：无 id 的请求不返回响应，节省带宽。

2. 错误处理

（1）标准化错误信息：错误响应中，data 字段可酌情附加调试详情（如堆栈跟踪），但要注意信息安全。

（2）自定义错误码：业务错误使用 -32000 到 -32099 范围。

3. 安全性

（1）字段过滤：避免在响应中返回敏感数据（如密码）。

（2）传输加密：使用 HTTPS 防止中间人攻击。

（3）限流与鉴权：通过 HTTP Headers（如 Authorization）实现身份验证。

4. 性能优化

（1）批量请求（Batch）：支持单次传输多个请求（减少 HTTP 开销）：

[
  {"jsonrpc": "2.0", "method": "sum", "params": [1, 2], "id": "1"},
  {"jsonrpc": "2.0", "method": "notify", "params": ["event"]}
]

（2）压缩数据：启用 Gzip 压缩 JSON 内容。

五、常见问题

1. 批量请求是否必须按顺序返回响应？

规范未强制要求顺序，但建议保持请求与响应顺序一致。

2. JSON-RPC 是否可以作为 RESTful 通信消息格式？

JSON-RPC 和 RESTful 是两种不同的 API 设计风格，虽都可基于 HTTP，但设计理念与适用场景差异显著，具体如下：

特性	JSON-RPC	RESTful
设计哲学	基于动作（Action）的远程调用	基于资源（Resource）的状态操作
HTTP 方法使用	通常只用 POST（所有请求发到同一端点）	使用 GET/POST/PUT/DELETE 等
URL 设计	单一端点（如 /api/jsonrpc）	资源路径（如 /users/{id}）
数据格式	固定 JSON 结构（含 method 和 params）	灵活（JSON/XML，通常无固定结构约束）
典型用例	复杂业务逻辑（如计算、事务）	CRUD 操作（如用户管理）

以删除一个用户为例：

JSON-RPC 需向统一端点（URL）发送如下消息格式：

{
  "jsonrpc": "2.0",
  "method": "deleteUser",
  "params": {"id": 123},
  "id": 1
}

RESTful 则只需发起一个 DELETE /users/123 请求。

综上所述，笔者认为 JSON-RPC 不适合作为 RESTful 的通信消息格式，原因有二：其一，调用方式不同，JSON-RPC 通过 method 参数调用指定方法，RESTful API 则依赖 HTTP 方法（如 GET/POST）和 URL 路径标识调用方法；其二，支持的协议范围不同，REST API 仅适配 HTTP 协议，JSON-RPC 支持常见网络协议，如 HTTP、TCP 等。