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 有以下区别：

二、消息类型

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
}

标准错误码：

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 需向统一端点（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 等。