协议机制：握手、协商与线路

沿用 01 章的场景：host（Cursor 或 Claude Desktop）连一个 GitHub server，让助手能读 issue、查 PR、提交评论。01 章关心"谁能调谁"，这一章把每一次调用还原成线路上真实流动的 JSON 字节——握手怎么发、能力怎么协商、一次 tools/call 在 stdin/stdout 上长什么样。

2.1为什么是 JSON-RPC 2.0

MCP 选 JSON-RPC 2.0 作消息层——它面向"调用一个具名方法"，与 function calling 的心智天然对齐，而非 REST 那套资源 / CRUD 模型。

底层机制（比文档深一层）：JSON-RPC 在 MCP 里扛着三个承重属性，缺一个这套协议就立不住。

• request id 做关联：一条长连接上请求和响应是乱序穿插的。每个 request 带一个 id，对应的 response 回填同一个 id——这样在同一条长生命周期双向通道上，发起方能把回来的结果对上是哪一次请求。没有 id，单通道上的多路并发请求就无法解多路复用。
• notification 做推送：一类消息没有 id、也不期待回复，专门承载 */list_changed（列表变更）、progress（进度）、cancellation（取消）。它是单向的"广播一声"，不占用请求-响应的配对。
• 对称（symmetric）：JSON-RPC 不区分谁是"客户端谁是服务端"——任一端都能发 request。这正是 03 章 server→client 调用（sampling / elicitation）能成立的协议基础：在消息层，server 给 client 发 request 与 client 给 server 发 request 完全同构。

还有一条关键性质：transport-agnostic（与传输无关）。同一个 JSON 消息形状，无论跑在 stdio 还是 HTTP 上都不变——2.8 讲的两种 transport 只换"管子"，不换"信件格式"。

对比 gRPC：gRPC 性能更高，但要求 protobuf 代码生成 + 强制 HTTP/2，调试时是二进制流。MCP 选 JSON-RPC，换来的是人类可读、可手抓包调试、零 codegen——一个 server 作者用任何语言拼 JSON 字符串就能对接。代价也实在：放弃了 HTTP 缓存、放弃了原生流式（后来靠 SSE 外挂补上）、放弃了默认强类型（改为每个 tool 自带一份 JSON Schema 描述参数）。

2.2三种消息形态

JSON-RPC 在线路上只有三种消息：request（带 id，要回复）、response（回填 id，带 result 或 error）、notification（无 id，不回复）。

底层机制（比文档深一层）：三种形态用一次 tools/call（让 GitHub server 创建一个 issue）摆出来看。注意 id 的有无如何决定"要不要等回复"。

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "create_issue",
    "arguments": { "title": "登录页 500", "body": "复现步骤见下" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [ { "type": "text", "text": "已创建 issue #1423" } ],
    "isError": false
  }
}

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

三点定死：① request 必带 id（数字或字符串，同会话内唯一）；② response 用同一个 id 回填，result 和 error 二选一、绝不并存；③ notification 没有 id 字段，发出即忘，对端不得回复。第三种形态正是 2.6 的进度 / 取消 / 列表变更全部走的通道。

2.3initialize 握手

每条 MCP 会话的第一笔交换必须是 initialize：三步——client 发请求、server 回响应、client 发 notifications/initialized 收尾。

底层机制（比文档深一层）：握手是严格的三步，方向交替，不能合并。

1. client → initialize request：带 protocolVersion（自己支持的最新版本）、capabilities（client 端能力，如 sampling / roots）、clientInfo（名称 + 版本）。
2. server → initialize response：回 它自己的 protocolVersion、capabilities（server 端能力，如 tools / resources）、serverInfo，外加可选的 instructions（给模型的使用说明）。
3. client → notifications/initialized：一条通知（无 id），告诉 server 初始化完成。这之后会话才进入 Operation 阶段。

版本是一个日期串（如 2025-06-18），不是语义化版本号。协商规则是一次"降级对齐"：client 在 step 1 发自己支持的最新版本；若 server 不支持该版本，server 在 step 2 回 它自己支持的最新版本；若 client 无法接受 server 回的这个版本，client 直接断开连接。没有来回拉锯，最多一个往返就定下版本或散伙。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "sampling": {},
      "roots": { "listChanged": true }
    },
    "clientInfo": { "name": "Cursor", "version": "1.4.0" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "subscribe": true, "listChanged": true },
      "prompts": {}
    },
    "serverInfo": { "name": "github-mcp", "version": "0.9.2" },
    "instructions": "用 create_issue 建 issue 前先 search_code 确认无重复。"
  }
}

2.4能力协商

握手时双方各自亮出一个 capabilities 对象；之后两端都只准使用已成功协商的能力，用未声明的特性即协议违规。

底层机制（比文档深一层）：capabilities 是分方向的两套。

• server 端能力：tools / resources / prompts / logging——即 01 章的三大 primitive 加日志。
• client 端能力：sampling / roots / elicitation——这正是 01 §1.6 埋下的那条反方向能力（server 反过来请求 client）。03 章把它们逐一展开。
• 子标志（sub-flags）：能力对象里可带细粒度开关。listChanged: true 表示"列表变更时会主动发 */list_changed 通知"；resources 还有 subscribe: true 表示"支持订阅单个资源的更新"。

运行期硬规则：协商之后，双方只能使用握手中成功协商出来的能力。server 没在 capabilities 里声明 prompts，client 就不准发 prompts/list；client 没声明 sampling，server 就不准向它发起 sampling 请求。用一个未亮过牌的特性，是协议违规——这条规则把"能不能用"从运行期试错提前到了握手期确定。

2.5lifecycle 三阶

一条 MCP 会话有三个阶段：Initialization（握手）→ Operation（正常收发）→ Shutdown（关闭），其中 Shutdown 走 transport 层而非协议消息。

底层机制（比文档深一层）：注意 Shutdown 没有一条"关闭"的 JSON-RPC 消息——它由 transport 负责，不同 transport 收场方式不同。

• stdio：client 先关闭 server 的 stdin（发 EOF）；server 若不在合理时间内自行退出，client 再发 SIGTERM，仍不退则 SIGKILL。
• Streamable HTTP：直接关闭 HTTP 连接即视为关闭会话。

另一处近期收紧：2025-06-18 把 Operation 阶段一条原为 SHOULD 的约束改成了 MUST（changelog "Change SHOULD to MUST in Lifecycle Operation"）——两端在 Operation 阶段必须尊重协商出的协议版本与能力，措辞从"建议"升格为"必须"。

2.6通知 / 进度 / 取消

长操作、取消、动态变更都走 notification——回到 2.2：这类消息没有 id、不期待回复，是单向推送。

底层机制（比文档深一层）：三类常见 notification，全部无 id。

• notifications/cancelled：在 params 里带上要取消的那个请求的 requestId，告知对端"别再处理它了"。因为是按 id 取消的，所以取消的目标必须是一个带 id 的 request——这也反证了 2.2 里"为什么 request 必须有 id"。
• progress 通知（notifications/progress）：长操作期间周期性上报进度。前提是发起请求时在 _meta 里带了 progressToken，对端据此把进度关联回那次请求。
• notifications/tools/list_changed（及 resources / prompts 的同类）：server 告诉 client "工具列表变了，重新 tools/list 拉一次"。这就是 MCP 的动态发现——工具集不是握手时定死的，可以运行期增删。前提是 server 在握手时声明了 tools.listChanged: true（呼应 2.4 的子标志）。

2.7错误模型

出错时 response 用 error 取代 result，是一个 { code, message, data } 对象，沿用 JSON-RPC 标准错误码。

底层机制（比文档深一层）：标准错误码区间固定。

• -32700 Parse error（JSON 解析失败）· -32600 Invalid Request（不是合法的 request 对象）
• -32601 Method not found（方法不存在）· -32602 Invalid params（参数非法）· -32603 Internal error（内部错误）
• -32000 到 -32099：保留给 server 自定义的实现错误。

MCP 把通用错误码复用到自己的语义上。一个常见例子：initialize 时若请求的协议版本不被支持，server 回 -32602（invalid params），并在 data 里附上 supported 与 requested 两个版本字段，让 client 看清差距。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unsupported protocol version",
    "data": { "supported": ["2025-03-26"], "requested": "2025-06-18" }
  }
}

2.8传输层：stdio 与 Streamable HTTP

MCP 当前定义两种 transport：stdio（本地，消息走 stdin/stdout）与 Streamable HTTP（远程，单端点 + 可选 SSE 流）；JSON-RPC 消息形状在两者上完全相同。

底层机制（比文档深一层）：两种 transport 的关键差异。

• stdio（本地）：host 把 server 作为子进程拉起，JSON-RPC 消息就在 stdin / stdout 上逐行流动。关键陷阱：stdout 就是线路本身——server 里任何 print() 或写到 stdout 的日志，都会混进 JSON 流、破坏解析，是真实会致命的 bug。所以 server 的日志必须全部走 stderr。这条是 04 章会回头点名的坑。
• Streamable HTTP（远程）：单个 HTTP 端点。client→server 用 HTTP POST 发请求；server→client 的流式（推送通知 / 进度）走可选的 GET + SSE（Server-Sent Events）。会话用 Mcp-Session-Id 响应头标识；自 2025-06-18 起，后续 HTTP 请求必须带 MCP-Protocol-Version 头（PR #548）声明协商出的版本。