2 工具协议：JSON Schema、function calling、MCP

第 1 章把工具定义成八字段契约，但那份契约还只是宿主内部的数据结构。一旦模型、宿主、工具分属三个进程甚至三个组织，契约就必须落到线上格式：模型怎么声明想调什么，宿主怎么校验与授权，工具怎么回传结果与错误，双方怎么确认彼此说的是同一版协议。协议解决的从来不是「模型会不会调用函数」，而是出现分歧时以谁为准。

这一章的主线是一条调用穿过三层边界：模型 provider 只产出意图，宿主把它变成可执行的调用，MCP 把调用送到工具进程。每穿过一层，信息都会丢失一部分；协议的价值是把丢失限制在可检测、可恢复的范围内。JSON Schema 约束参数形状，function calling 约束模型与宿主之间的一轮交换，MCP 约束宿主与工具之间的能力、调用、结果与错误，OAuth 则约束「谁有权让谁做什么」。

版本坐标必须先说清：MCP 最新规范是 2026-07-28，上一版是 2025-11-25。新实现应面向 2026-07-28，但必须能识别仍在使用 initialize 握手的旧 server。把 initialize 当永恒，或者把无状态当默认，都会在真实部署里翻车；本章会给两版对照表与迁移路径。

读图：从左到右是控制流，不是信任流。模型只产出 tool_calls；宿主做校验、授权、路由；MCP 只负责把调用送到 server。中间的请求帧里，参数可能来自网页、文件或另一个工具的输出，所以「schema 合法」不等于「可以执行」。底部两行是版本坐标：新版把 initialize 与协议级会话去掉了，新实现不应再把握手当默认前提。

2.1 三方与分层：模型只产出意图，宿主负责执行

先看一次调用里三个角色各自能决定什么。把这张表记住，后面所有协议细节都能挂上去。

很多实现把这张表压成一行：模型输出 JSON，宿主直接 json.loads 后调用函数。Demo 能跑，生产会出三类事故：模型声称做了但没做；参数越权但没人拦；执行失败被模型当成成功继续。三者都不是模型能力问题，而是宿主放弃了执行层。

┌──────────────────────────────────────────────────────────────┐
│ 模型 provider                                                 │
│   输入：messages + tools[]（名字、描述、JSON Schema）          │
│   输出：tool_calls[{id, name, arguments}]      ← 只是意图      │
└───────────────────────────┬──────────────────────────────────┘
                            │ ① 模型 API 边界（格式约束）
┌───────────────────────────▼──────────────────────────────────┐
│ 宿主 runtime                                                  │
│   解码 → 校验 → 授权 → 去重 → 路由 → 记账 → 回填观察           │
│   能拒绝、能改写、能延迟、能要求人工确认                        │
└───────────────────────────┬──────────────────────────────────┘
                            │ ② MCP / HTTP 边界（JSON-RPC 契约）
┌───────────────────────────▼──────────────────────────────────┐
│ MCP server / 工具进程                                          │
│   inputSchema 再校验 → 前置条件 → 副作用 → result/isError       │
│   持有凭证、文件句柄、数据库连接                                │
└──────────────────────────────────────────────────────────────┘
   ③ 进程/网络边界：OS 权限、沙箱、审计（第 3、4、11 章）

读图：三条横线是三种边界，不是三种信任。① 只保证模型输出可解析；② 只保证双方对帧格式一致；③ 才限制真实副作用。每跨一条边界，信息都会丢：模型看不到宿主的权限表，server 看不到模型为什么选它。协议的工作是把这种丢失变成可检测的偏差——id 对不上、schema 不合法、能力没声明、audience 不匹配，都能在造成副作用之前被拦下。

这个三元组是第 1 章八字段工具契约 定义 1.4.1 的线上投影：给模型看的部分变成 $E$，执行器内部的前置条件、幂等性、权限留在宿主；两者不是替代关系，而是同一契约的两个视图。

同一份意图，在两层协议里有两种编码。模型 API 层（OpenAI Chat Completions 形状）：

{
  "id": "call_demo_1",
  "type": "function",
  "function": {
    "name": "fs_read",
    "arguments": "{\"path\":\"seed.txt\"}"
  }
}

MCP 层：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "fs.read",
    "arguments": {"path": "seed.txt"}
  }
}

两个 JSON 说的是同一件事，但有三处关键差异。arguments 在模型层是字符串（可能是半截 JSON），到 MCP 层必须是对象；id 在模型层由 provider 生成、只在一次响应内有效，到 MCP 层由客户端生成、在一条连接上唯一；错误在模型层通常没有位置，只能塞进文本，到 MCP 层有 error 与 isError 两条通道。把这三处理顺，才算真正「支持工具调用」，而不只是会解析一个函数名。

反过来，协议不能替你做的事也要说清：它不判断一个工具该不该存在，不判断参数里的路径是否敏感，不判断调用者是否被诱导。这些属于权限、沙箱与安全（第 3、4、11 章）。协议只保证「如果一切按契约发生，双方看到的是同一件事」。

2.2 JSON Schema：约束、strict 与 2020-12

JSON Schema 是三方唯一共同读取的字段：模型据此生成参数，宿主据此预校验，server 据此最终校验。三方对同一份 schema 的理解只要有一点偏差，就会出现「模型觉得合法、宿主放行、server 崩溃」的缝隙。

先澄清六个最容易写反的语义：

required 与 additionalProperties 的组合值得单独记：{"required":["path"]} 允许 {"path":"a","extra":1}；要拒绝额外字段，必须显式写 "additionalProperties": false。很多「schema 校验过了但 server 炸了」的事故，就是宿主只查了 required，把多余字段原样转发。

integer 的判定也值得留意：2020-12 规定「零小数的数字」算整数，所以 1.0 合法；但不少实现直接按宿主语言类型判断（Python 的 isinstance(1.0, int) 为假），于是同一份 schema 在两个校验器上给出不同结果。跨语言时要么统一用整数传输，要么在边界显式规范化。

2.2.1 2020-12 与 draft-07 的差别

MCP 2026-07-28 规定：schema 没有 $schema 字段时，默认按 JSON Schema 2020-12 解释；实现必须支持 2020-12，可以额外支持其他方言。这条规定把「方言漂移」变成了显式错误，而不是静默的宽松解释。

这张表说明什么：schema 不是「一段永远兼容的 JSON」，它有方言。跨系统传输时，要么显式写 $schema，要么双方约定只使用交集子集；靠「应该差不多」会在大半年后炸。

2020-12 还有一个安全相关的细节：$ref 可以指向绝对 URI，但 MCP 明确要求实现不得默认解引用网络 URI。否则一个恶意 server 返回的 schema 就能让客户端去请求内网地址，形成 SSRF（第 2.8 节）。需要远程引用时，必须显式开启、限制主机、拒绝回环与私网地址、加超时与大小上限。

2.2.2 strict 模式：三个条件，不是一种方言

OpenAI 的 strict 不是 JSON Schema 的新方言，而是「把 schema 编译成受约束解码」的一组额外要求。要让 strict: true 真正生效，核心是三条结构要求：

1. 根是 object，且每一层 object 都写 "additionalProperties": false；
2. 每个在 properties 里出现的键都必须列进 required；
3. 「可选」用可空类型表达（例如 ["string","null"]），而不是从 required 里省略。

{
  "type": "object",
  "properties": {
    "path": {"type": "string"},
    "encoding": {"type": ["string", "null"], "enum": ["utf-8", "base64", null]}
  },
  "required": ["path", "encoding"],
  "additionalProperties": false
}

这段 schema 里，encoding 在语义上可选，但在结构上必填：调用方要么给 "utf-8"，要么给 null。这不是冗余，而是为了让受约束解码有确定的形状——模型不能「忘记」一个字段，只能显式选择空值。

一个最小校验器的核心逻辑只有十几行。下面是 experiments/ch02/mcp_stdio_server.py 里实际使用的子集（省略了数值、布尔等分支）：

def validate(schema, value, path="$"):
    if schema.get("type") == "object":
        if not isinstance(value, dict):
            return [f"{path}: expected object"]
        errors = [f"{path}.{k}: required property is missing"
                  for k in schema.get("required", []) if k not in value]
        props = schema.get("properties", {})
        if schema.get("additionalProperties") is False:
            errors += [f"{path}.{k}: unexpected property" for k in value if k not in props]
        for key, sub in props.items():
            if key in value:
                errors += validate(sub, value[key], f"{path}.{key}")
        return errors
    if schema.get("type") == "string" and not isinstance(value, str):
        return [f"{path}: expected string"]
    return []

这段代码故意只覆盖本章用到的关键字。真实实现要用完整校验器，并且在宿主与 server 两侧各校验一次：宿主校验是为了在产生副作用前拦住明显错误，server 校验是因为宿主可能被绕过、也可能是另一个团队写的。

MCP 对 schema 还有两条工程约束：inputSchema/outputSchema 必须是合法 schema 对象，不能为 null；组合关键字（anyOf、oneOf、allOf、if/then/else）与 $defs 可能被恶意构造为校验器的 DoS 向量，实现应限制深度、子 schema 数量与单次校验时间。schema 本身也是不可信输入。

schema 描述的是单次调用的形状；一次调用在时间上的形状——谁先谁后、能否并行、流式片段怎么拼——由下一节的 function calling 决定。

2.3 function calling：tools、tool_choice、并行与流式

function calling 是模型 API 层的交换格式。不同 provider 的字段名不一样，但回路相同：宿主把工具目录放进请求，模型返回一个或多个调用意图，宿主执行后把结果按 id 回填，再次请求模型。先把 OpenAI Chat Completions 的形状走一遍，再对照 Responses API。

请求侧只保留关键字段：

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "fs_read",
        "description": "读取 workspace 内的 UTF-8 文本文件；path 必须是相对路径。",
        "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string", "minLength": 1}},
          "required": ["path"],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": false
}

模型返回的调用意图：

{
  "id": "chatcmpl_demo",
  "choices": [
    {
      "finish_reason": "tool_calls",
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_demo_1",
            "type": "function",
            "function": {
              "name": "fs_read",
              "arguments": "{\"path\":\"seed.txt\"}"
            }
          }
        ]
      }
    }
  ]
}

注意 arguments 是字符串，不是对象。它可能是 ""、"{}"、半截 JSON，或者带转义的嵌套 JSON；宿主必须自己 json.loads 并处理解析失败。把这一步交给模型「保证合法」是常见的错误：strict 能降低概率，但不能替代宿主的解析与校验。

tool_choice 有四种取值，用途完全不同：

parallel_tool_calls 在 Chat Completions 里默认是 true。并行不是免费的：两个写操作可能冲突，后一个可能依赖前一个的输出，两个调用可能对同一文件做「读—改—写」。宿主要么显式关闭并行，要么在收到多个调用后做依赖分析，把有冲突的调用串行化。判定规则可以很朴素：只读且参数无重叠的调用可并行；任何写调用默认串行，除非工具有幂等键且作用域不相交。

回填结果时，assistant 消息要原样带上 tool_calls，然后每个调用一条 role: "tool" 消息：

[
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_demo_1",
        "type": "function",
        "function": {"name": "fs_read", "arguments": "{\"path\":\"seed.txt\"}"}
      }
    ]
  },
  {
    "role": "tool",
    "tool_call_id": "call_demo_1",
    "content": "{\"path\":\"seed.txt\",\"bytes\":11,\"content\":\"alpha\\nbeta\\n\"}"
  }
]

三条不变量经常被违反：每个 tool_call 必须有且只有一条对应结果；tool_call_id 必须来自同一轮；未执行的调用也必须回填一条显式拒绝，不能静默丢弃。少一条，多数 provider 会直接返回 400；少数会容忍，但模型会在下一轮「忘记」自己调过什么。

2.3.1 流式：按 index 拼，不按到达顺序拼

流式响应里，tool_calls 是增量下发的。第一块通常带 index、id、type 与函数名，后续块只带 index 与 arguments 片段：

chunk 1  delta.tool_calls[0] = {index: 0, id: "call_demo_1", type: "function",
                                function: {name: "fs_read", arguments: ""}}
chunk 2  delta.tool_calls[0] = {index: 0, function: {arguments: "{\"path\":"}}
chunk 3  delta.tool_calls[0] = {index: 0, function: {arguments: "\"seed.txt\"}"}}
chunk 4  finish_reason = "tool_calls"

正确做法是维护 index -> {id, name, arguments_buffer} 的映射，每块按 index 追加，收到 finish_reason 后再统一 json.loads。三个细节：index 是调用在本次响应里的序号，不是数组下标，多个调用可能交错到达；id 与 name 只出现一次，后续块没有；arguments 片段可能在任意字节处切开，包括 UTF-8 多字节字符与转义序列，逐块解析必然失败。

2.3.2 Responses API 与 Chat Completions 的字段差异

两套接口表达同一回路，但字段层级不同。迁移时最容易错的不是名字，而是「谁包着谁」：

这张表说明什么：适配器不能只改字段名，还要改「状态放在哪」。Chat Completions 把历史放在 messages 里，Responses 把一部分历史放在服务端的 response 对象里；前者更容易审计与重放，后者更省往返。选哪个取决于你的可观测性与数据保留要求，不是哪个更新。

结构化输出（structured outputs）与工具参数是两件事。前者约束最终答案的形状，后者约束动作参数的形状。两者都用 JSON Schema，但失败语义不同：答案 schema 失败通常重试或降级为文本；参数 schema 失败应该变成一条 isError 观察，让模型改参数（第 2.7 节）。

宿主的执行伪代码可以压成十几行：

resp ← model.chat(messages, tools)
calls ← decode(resp)                  # 解析失败 → 回填 EINVAL，不重试模型
for c in calls:
    if c.name not in registry: result[c.id] ← ENOTOOL
    elif not validate(registry[c.name].schema, c.args): result[c.id] ← EINVAL
    elif not authorize(c): result[c.id] ← EPERM
if parallel and all_readonly(calls): run_concurrently(calls, deadline)
else: run_in_order(calls, deadline)
append(assistant_message_with_calls)
append(each result keyed by id)

四个边界必须显式处理：finish_reason == "length" 说明参数可能被截断，不能执行；content 与 tool_calls 同时存在时，文本可能是在解释调用，不能当最终答案；同一响应里出现重复 id 时，保留第一个、拒绝其余；finish_reason == "tool_calls" 但 tool_calls 为空，是 provider 异常，应重试一次而不是当成功。

到这里，模型与宿主之间的回路已经闭合。但宿主与工具之间还没有协议：工具可能是本地函数、另一个进程、一个远程服务，甚至别人家的 SaaS。下一节的 MCP 就是这后半段的通用语言。

2.4 MCP 原语：tools/resources/prompts 与能力协商

MCP（Model Context Protocol）是宿主与工具之间的 JSON-RPC 2.0 协议。它不替代模型 API，也不规定模型怎么选工具；它规定的是：工具如何声明自己、宿主如何调用、结果与错误如何回传、双方如何确认能力边界。用一句话概括：MCP 是工具侧的操作系统调用表——不是插件市场，也不是权限系统。

JSON-RPC 2.0 只有三种消息。request 带 id、method、params；response 必带同一 id（解析失败、id 不可读时可为 null），并在 result 与 error 中二选一；notification 没有 id，接收方不得回复。JSON-RPC 允许 id 为 null（不推荐），MCP 收紧为字符串或整数、不得为 null，且同一发送方未完成的请求 id 不得重复。错误对象固定三字段：code（整数）、message（一句话）、data（可选的结构化补充）。

{"jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": {"name": "nope"}}
{"jsonrpc": "2.0", "id": 7, "error": {"code": -32602, "message": "Unknown tool: nope"}}
{"jsonrpc": "2.0", "method": "notifications/cancelled", "params": {"requestId": 7}}

服务端有三个原语，控制点各不相同：

客户端侧在 2025-11-25 还有 roots、sampling、elicitation 三个能力；2026-07-28 只保留 elicitation（并且改为通过 MRTR 传递），roots 与 sampling 进入弃用。这个变化不是删功能，而是把「server 反向控制 client」改成「client 在一次请求内决定是否配合」。

tools/list 的响应包含工具名、描述、输入/输出 schema 与注解。下面是实验里真实返回的第一个工具（只保留一个，字段未改）：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "tools": [
      {
        "name": "fs.read",
        "title": "Read a text file",
        "description": "读取 workspace 根目录内的 UTF-8 文本文件。path 必须是相对路径；不要用于读取二进制文件或目录。",
        "inputSchema": {
          "type": "object",
          "properties": {"path": {"type": "string", "minLength": 1, "maxLength": 200}},
          "required": ["path"],
          "additionalProperties": false
        },
        "outputSchema": {
          "type": "object",
          "properties": {
            "path": {"type": "string"},
            "bytes": {"type": "integer", "minimum": 0},
            "content": {"type": "string"}
          },
          "required": ["path", "bytes", "content"],
          "additionalProperties": false
        },
        "annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        }
      }
    ],
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

三个字段值得停一下。outputSchema 让宿主可以在把结果喂给模型前校验结构；annotations 是提示，不是权限；ttlMs 与 cacheScope 是 2026 新增的缓存提示，前者说这份列表多久内可视为新鲜，后者说能否跨授权上下文共享。缓存不是可选的优化：没有 ttlMs 时客户端应按 0 处理，也就是每次都重新拉。

2.4.1 注解只是提示

规范明确要求：除非 server 可信，客户端必须把注解当作不可信。原因很直接——注解由 server 自己声明，一个被投毒的 server 可以把 rm -rf 标成 readOnlyHint: true。默认值也刻意保守：没声明就当作「可能破坏、可能不幂等、可能访问开放世界」。

规范建议工具名满足：长度 1–128，字符集为 ASCII 字母、数字、下划线、连字符与点，大小写敏感，同一 server 内唯一。聚合多个 server 的宿主必须处理重名，通常加 server 前缀；serverInfo.name 不保证唯一，不能拿它当命名空间。

2.4.2 resources 与 prompts

resources 面向「读数据」，URI 是标识符，不一定是文件路径。工具结果里可以返回 resource_link（让客户端自己决定要不要读）或 resource（内嵌内容）。前者适合大对象与需要权限的数据，后者适合小段上下文。

{"jsonrpc": "2.0", "id": 9, "method": "resources/read",
 "params": {"uri": "file:///tmp/ch02-mcp/seed.txt"}}

{"jsonrpc": "2.0", "id": 9, "result": {
  "contents": [{"uri": "file:///tmp/ch02-mcp/seed.txt", "mimeType": "text/plain",
                "text": "alpha\nbeta\n"}]}}

prompts 面向「用户主动选择的模板」：prompts/list 列出模板与参数，prompts/get 返回一组消息。它不应该被宿主自动注入——那是 system prompt 的职责；prompts 的语义是「用户点了一下这个模板」。

能力协商要回答三个问题：对方会不会回答这个方法（能力位）、我这个请求需不需要对方的能力（例如 MRTR 需要 elicitation）、回答了是否等于授权（不等于）。前两个问题决定「能不能调」，第三个问题决定「该不该执行」。很多实现只检查第一个，于是把「server 声明了 tools」误当成「这个调用者可以用所有 tools」。

三个原语解决「有什么、怎么调、结果是什么」；它们没有解决「第一次见面怎么确认对方是谁、说哪版」。这就是生命周期与版本协商。

2.5 生命周期：从 initialize 到无状态

MCP 的版本号是日期字符串，不是 semver。2026-07-28 指一份具体修订，不承诺与 2025-11-25 的补丁级兼容。两版之间不是小改：2026-07-28 把协议级会话与握手整个移除，改成每个请求自带元数据。理解这个断点，比记住字段名更重要。

2025-11-25（legacy）                        2026-07-28（modern）
client                 server               client                 server
  │ initialize           │                    │ server/discover      │
  │─────────────────────>│                    │─────────────────────>│
  │←─────────────────────│                    │←─────────────────────│
  │ notifications/       │                    │                      │
  │ initialized          │                    │  （没有握手，没有会话） │
  │─────────────────────>│                    │                      │
  │ tools/list           │                    │ tools/list           │
  │─────────────────────>│                    │─────────────────────>│
  │←─────────────────────│                    │←─────────────────────│
  │                      │                    │                      │
  connection = session                       每个请求自带 _meta
  断线重连必须重新握手                          断线重试换新 id（副作用仍需幂等）

读图：左边前两帧建立上下文，后面所有帧都依赖它；右边每一帧都是自包含的，server 不要求你复用同一条连接。代价从「连接建立时的往返」变成「每一帧的字节」；收益是任意请求可以落到任意实例，失败恢复不必重放握手。注意右边仍然可以有状态——购物车、事务、长任务——但状态必须由 server 显式发一个 handle，客户端在后续参数里带回来，而不是靠连接隐式维系。

2025-11-25 的握手长这样（实验 trace 的真实响应，已缩进）：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": {"listChanged": false},
      "resources": {"subscribe": true, "listChanged": false},
      "prompts": {"listChanged": false},
      "logging": {}
    },
    "serverInfo": {"name": "ch02-stdio-server", "version": "1.0.0"},
    "instructions": "教学 server：先 initialize，再发 initialized 通知。"
  }
}

客户端在 initialize 里给出自己支持的版本、能力与身份；server 返回它选的版本与能力；客户端再发 notifications/initialized，双方才进入操作阶段。版本不匹配时，server 返回自己支持的最新版，客户端若不支持就断开。这套协商只发生一次，之后的请求都默认沿用。

2026-07-28 把同样的信息拆进每一帧：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {"name": "ch02-client", "version": "1.0.0"},
      "io.modelcontextprotocol/clientCapabilities": {"elicitation": {}}
    }
  }
}

protocolVersion 与 clientCapabilities 是必填；clientInfo 是建议填。server 在处理请求前检查版本：不认识就返回 -32022 UnsupportedProtocolVersion，并在 data.supported 里列出自己支持的版本；缺字段返回 -32602。结果侧对应地带 _meta.io.modelcontextprotocol/serverInfo，但它是自报的，只能用于展示与排障，不能用于安全决策。客户端还要兼容旧 server：收到缺少 resultType 的结果时，必须按 complete 处理，而不是判协议错误。

两版的关键差异可以压成一张表。这张表建议直接放进你的迁移文档，而不是只留在脑子里：

这张表说明什么：2026 不是「加了几个字段」，而是把「连接即上下文」改成「请求即上下文」。所有依赖连接状态的设计——会话粘滞、GET 流广播、断点续传——都要重新设计。

方法可用性速查。 迁移时最常问的是「这个方法还在不在」，直接查表比翻 changelog 快：

这张表只列核心方法。扩展方法（如 UI、tasks）随扩展走，不在核心版本矩阵里。

2.5.1 MRTR：把反向请求变成两轮往返

旧版里，server 可以在处理 tools/call 的过程中反向发一个 elicitation/create 请求，等客户端返回后再继续。这要求连接保持、双向通道可用、server 记住中间状态。新版把这件事改成多轮往返（MRTR）：server 不主动发请求，而是返回一个 resultType: "input_required" 的结果，里面带 inputRequests；客户端收集输入后，用新的请求 id 重发原请求，并带上 inputResponses 与 requestState。

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "resultType": "input_required",
    "inputRequests": {
      "confirm_write": {
        "method": "elicitation/create",
        "params": {
          "mode": "form",
          "message": "允许写入 out.txt（5 字节）？",
          "requestedSchema": {
            "type": "object",
            "properties": {"confirm": {"type": "boolean"}},
            "required": ["confirm"],
            "additionalProperties": false
          }
        }
      }
    },
    "requestState": "eyJwIjogImV5SnBZWFFpT2pF...(省略)"
  }
}

server 只能请求客户端声明过的能力：clientCapabilities 里没有 elicitation 时，应返回 -32021 MissingRequiredClientCapability，而不是硬发一个 inputRequests。

requestState 是不透明字符串，客户端不得解析或修改，重试时原样带回。它让 server 不必在两次请求之间保存状态：需要记住的上下文（写哪个文件、内容哈希、过期时间）由 server 自己编码进去，并做完整性保护。这也意味着它经过客户端，必须当作攻击者可控输入：要校验 MAC、过期时间、主体、以及是否与本次参数匹配。实验里的 fs.write 就是这么做的；篡改尾部四个字符会得到 -32602。

生命周期解决「我们说的是不是同一版」；传输解决「帧怎么过去、断了怎么办」。后者才是事故高发区。

2.6 传输与可靠性：stdio、Streamable HTTP、取消与重试

2.6.1 stdio：一行一帧，stdout 只许协议

stdio 传输的规则少而硬：

• 每条消息是一行 JSON，消息内不得有裸换行（字符串里的换行由 JSON 转义成 \n）；
• server 从 stdin 读、往 stdout 写；stdout 只能写协议帧；
• 日志、调试输出、进度条一律写 stderr；客户端不应把 stderr 当错误信号；
• 所有消息共享一条通道，靠 JSON-RPC id 关联请求与响应，没有 per-request 流；
• 取消用 notifications/cancelled，因为 stdio 没有「关掉某条响应流」这种粒度；
• 关闭 stdin 是优雅停机的首要信号；不退出再升级到 SIGTERM、SIGKILL。

import json, sys

def write_frame(stream, frame):
    line = json.dumps(frame, ensure_ascii=False, separators=(",", ":"))
    assert "\n" not in line, "stdio frame must be one line"
    stream.write(line + "\n")
    stream.flush()

print() 调试是 stdio server 的第一号事故：一行 print("debug") 就会让客户端收到无法解析的帧，随后整条连接被判定为协议错误。更隐蔽的是第三方库把日志写到 stdout，或者 json.dumps 的 indent 参数把一帧拆成多行。

2.6.2 Streamable HTTP：一个端点，两种响应

Streamable HTTP 把每个 JSON-RPC 消息变成一次 POST。客户端必须同时接受两种响应：单个 JSON 对象，或一条 SSE 流。SSE 流里可以先有与本请求相关的 notifications/progress、notifications/message，最后才是最终响应；最终响应之后流应结束。

POST /mcp HTTP/1.1
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: fs.read

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"fs.read","arguments":{"path":"seed.txt"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{"elicitation":{}}}}}

MCP-Protocol-Version 必须与 body 里 _meta 的版本一致；Mcp-Method 与 Mcp-Name 让网关不必解析 body 就能路由。头与 body 不一致时，server 必须返回 400 与 -32020 HeaderMismatch——这是防止「负载均衡按头路由、server 按 body 执行」的经典混淆。未知方法返回 404 加 -32601，以便与旧 HTTP+SSE server 的 404 区分。

旧版（2025-11-25）在这套机制之上还有四样东西：initialize 响应可带 Mcp-Session-Id，后续请求必须带上；GET 可以打开一条独立 SSE 流；DELETE 终止会话；Last-Event-ID 可以续传。2026-07-28 全部移除：只支持新版的 server 对 GET/DELETE 建议回 405，收到 Mcp-Session-Id 应忽略且不再签发，收到 Last-Event-ID 应忽略。SSE 断流不再可续，断掉的请求就是丢了，客户端必须用新的 id 重发。

安全性上，Streamable HTTP 有三条基线要求：校验 Origin，不合法回 403（防 DNS rebinding，MUST）；本地运行只绑 127.0.0.1（SHOULD）；所有连接都应认证（SHOULD）。前两条缺任何一条，一个恶意网页就可能驱动你本机的 MCP server。

2.6.3 可靠性：超时、取消与重试的边界

先看一张故障对照表。它的重点是第三列：客户端能不能确定副作用已经发生。

这张表说明什么：只有「确定没执行」的失败可以无条件重试。读超时、SSE 断流、会话过期都属于「不确定」，必须靠幂等键或去重表兜底；没有这两样，重试就是在赌。

定理的工程含义不是「不要重试」，而是「重试必须与幂等设计配套」。三条可执行的规则：读操作与显式幂等键的写操作可以重试；不可逆写默认不自动重试，转人工或查询外部状态；所有重试计入独立预算，带指数退避与抖动，且不能重试 EPERM/EACCES 这类权限错误。

取消也不是「保证没执行」。客户端发 notifications/cancelled，或者关掉 SSE 响应流，server 应尽快停止，但副作用可能已经发生。取消的语义是「别再往下做」，不是「把已经做的撤回」。需要撤回的场景要靠补偿动作，而不是取消。

观测一次协议会话，不需要抓包工具，客户端已经把帧写成了 JSONL：

python3 experiments/ch02/mcp_client.py --era 2026 --root /tmp/ch02-mcp \
  --trace experiments/ch02/trace-2026.jsonl --quiet
jq -r 'select(.dir=="recv" and .frame.error) | [.frame.id, .frame.error.code, .frame.error.message] | @tsv' \
  experiments/ch02/trace-2026.jsonl

checks: ok=28 fail=0
7	-32602	Unknown tool: nope
8	-32601	Method not found: tools/frobnicate
9	-32602	Invalid params: missing _meta
10	-32022	Unsupported protocol version
14	-32602	Invalid params: bad requestState

这五行覆盖了五类协议错误：未知工具、未知方法、缺元数据、版本不支持，以及被篡改的 requestState。它们都没有走到工具执行层——这正是「在副作用之前失败」的样子。第 2.7 节会把「哪些错误该走这条通道、哪些该走 isError」讲清。

2.7 结果与错误：isError、结构化内容与错误码

协议里最容易偷懒的决定，是把所有失败都塞进一条通道。MCP 给了两条：JSON-RPC 的 error，与工具结果里的 isError: true。选错的代价很具体——模型看不到本可以自纠的参数错误，或者宿主把一次可恢复的业务失败当成连接崩溃。

先看错误码的分区。JSON-RPC 2.0 把 -32768..-32000 整段保留给协议自身与实现，其中 -32000..-32099 是实现自定义的服务器错误区。MCP 再把这一段切开：-32000..-32019 是遗留实现用过的，新代码不应再分配；-32020..-32099 保留给规范。这条分区规则是 2026-07-28 才明确的，旧实现里各种自定义码混用，是迁移时的主要噪音源。

这张表说明什么：「模型能不能改」是分通道的第一判据。参数类型错、枚举越界、日期格式错，模型看到具体原因后有机会改对，应走 isError；方法不存在、版本不支持、头不匹配，模型改不了，走 JSON-RPC error 让宿主处理。规范明确把「输入校验错误」列为工具执行错误，而不是协议错误，原因就在这里。

结果侧的内容也有结构。content 是给模型看的非结构化块数组（text/image/audio/resource_link/resource），structuredContent 是给程序校验的结构化值。规范建议：返回结构化内容时，同时把序列化 JSON 放进一个 text 块，兼容只认 content 的旧客户端。structuredContent 与模型的「结构化输出」是两件事：前者是 server 产出的结果数据，后者是约束模型生成的 schema。

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "resultType": "complete",
    "content": [
      {"type": "text", "text": "{\"error\": {\"code\": \"EINVAL\", \"message\": \"$.a: expected number, got str\", \"retryable\": true}}"}
    ],
    "structuredContent": {
      "error": {"code": "EINVAL", "message": "$.a: expected number, got str", "retryable": true}
    },
    "isError": true
  }
}

这段是实验里的真实响应（缩进调整过）。三个字段各司其职：isError 告诉宿主「这是工具层失败，不是连接失败」；content 让模型能读到原因；structuredContent.error 给宿主稳定的机器码与 retryable。错误对象里不要放栈、SQL、内部 URL 或 token——它们既可能泄密，也会把模型的注意力带偏。

一个可复用的错误对象建议包含以下六个字段，缺一个就会让某一方靠猜：

code 与 message 的分工要固定：程序读 code，模型读 message，人读 suggested_action。三者混用会导致「改文案破坏了监控」或「模型看不懂机器码」。

宿主收到不同错误时的策略：

这张表说明什么：错误处理不是 try/except，而是一棵决策树。树的第一层是「通道」，第二层是「可重试性」，第三层才是「文案」。把三层压成一层，必然出现「权限错误重试三次」或「参数错误直接终止」这两种极端。

再看一眼 trace 里的分布，确认失败都发生在该发生的层：

jq -r 'select(.dir=="recv" and .frame.result) | [.frame.result.resultType, .frame.result.isError] | @tsv' \
  experiments/ch02/trace-2026.jsonl | sort | uniq -c

   2 complete	
   4 complete	false
   2 complete	true
   1 input_required	

两行 complete 没有 isError 字段，是 server/discover 与 tools/list；四个成功调用、两个工具级失败、一个 MRTR 中间结果。协议错误不在这个统计里，因为它们走 error 通道，被前一条 jq 单独筛出。把两张表放在一起，才能回答「失败有多少、分别在哪一层」。

2.8 授权：OAuth 2.1、audience 与 confused deputy

前面所有协议都假设「调用者有权」。真实系统里，这个假设要靠 OAuth 2.1 兑现。MCP 的授权模型很明确：受保护的 MCP server 是 OAuth 2.1 资源服务器，MCP client 是 OAuth 客户端，授权服务器（AS）可以是独立服务。server 不签发 token，只验证 token；client 不为 server 保存密码，只持有 AS 签发的、绑定到该 server 的 token。

一次完整的授权流程：

1. client 不带 token 请求，server 返回 401，并在 WWW-Authenticate 里给出 resource_metadata 与所需 scope；
2. client 拉取受保护资源元数据（RFC 9728），从中找到 AS；
3. client 通过 AS 元数据（RFC 8414 或 OIDC Discovery）找到授权端点与 token 端点；
4. client 注册：优先用 CIMD（Client ID Metadata Documents），退回预注册或 DCR；
5. client 生成 PKCE 参数，带 resource（RFC 8707）发起授权请求；
6. 用户授权后，client 用 code + verifier + resource 换 token，并校验 iss（RFC 9207）；
7. 之后每次请求都带 Authorization: Bearer <token>；server 校验签名、过期、audience 与 scope。

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="files:read"

这条 401 是发现流程的起点，不是终点。客户端不应硬编码 AS 地址，也不应假设所有 server 共用一个 AS；元数据里的 authorization_servers 才是权威来源。

这张表说明什么：MCP 没有发明授权，它把一组现成 RFC 组合成一条最小路径。工程上不要自己发明「用 API key 代替 OAuth」的捷径——那会同时失去 audience、过期、撤销与审计。

scope 的粒度是设计题，不是越细越好。按「一个用户能理解的授权单元」切：files:read、files:write、issues:write，而不是按每个工具切一个 scope。太细会让用户在授权页面上点几十次，最终形成「全部同意」的肌肉记忆；太粗则一次授权覆盖所有危险动作。可行的折中是「粗 scope + 每工具映射 + 运行时 step-up」：初始只申请只读，遇到写操作返回 403 insufficient_scope，客户端把当前 scope 与挑战里的 scope 取并集再授权，且限制重试次数。

2.8.1 token 透传与 confused deputy

规范里有两句很短、但经常被忽略的 MUST：MCP server 不得接受不是发给它的 token；不得接受或中转任何其他 token。违反这两句，就会得到 token passthrough（透传）与 confused deputy（混淆代理）。confused deputy 的成立需要两个条件：代理拥有调用者没有的权限；代理在调用者的请求上使用了该权限，却没有校验调用者是否有权。

2.8.2 其余四类授权事故

SSRF。 客户端要拉取 resource_metadata 与 AS 元数据，这两个 URL 都可能由不可信的 server 提供。恶意 server 可以让客户端请求 http://127.0.0.1:8500/v1/... 或云元数据地址。控制：只允许 HTTPS、主机 allowlist、拒绝回环/链路本地/私网、禁止重定向、超时与响应大小上限、记录实际拉取的 URL。schema 的远程 $ref 同理（第 2.2 节）。

状态句柄劫持。 2025 的 Mcp-Session-Id 如果是可猜测的短字符串，攻击者可以冒充他人会话；2026 的显式 handle 也常被当成 bearer token 使用。控制：高熵、不可解析、绑定主体、每次调用校验归属、设置 TTL、泄露后可撤销。handle 是名字，不是能力——server 每次都要重新授权。

本地 server 失配。 stdio server 通常以当前用户权限运行，能读用户能读的一切。它不是安全边界，也不应接收 HTTP 世界的 token。正确做法是从环境或 OS keychain 取该 server 专用的最小凭证，并用第 3、4 章的沙箱与权限把它的能力收紧。把本地 server 当成「可信内网」是常见错觉。

开放重定向与 mix-up。 授权响应可能被重定向到攻击者控制的 URI；多 AS 环境下，客户端可能把 code 发给错误的 AS。控制：严格匹配注册的 redirect_uri、校验 iss、把 PKCE verifier 与 AS 绑定、拒绝不在元数据里的端点。

这张表把 2.8.1 的两类也列进来，共六类；其中只有 SSRF 是「网络层」问题，其余都是「把认证当授权」或「把句柄当能力」。授权设计的核心不是接上 OAuth，而是让每一个副作用都能回答「这是谁授权的」。

2.9 互操作与迁移：版本矩阵、弃用与事故复盘

两版协议会长期共存。迁移的第一件事不是改代码，而是画矩阵：你的客户端是什么时代，对端 server 是什么时代，组合起来会发生什么。

这张表说明什么：兼容不是「支持所有版本」，而是「在每一格都有确定行为」。最危险的一格是「2026 客户端 × 仅 2025 server」：如果没有探测，客户端会把 -32600/-32601 当成致命错误，或者更糟——旧 server 不校验握手，直接把 tools/call 当 legacy 语义执行。

弃用项也要列清楚。弃用不等于立刻不可用，而是「仍能工作，但新实现不应采用，未来版本会移除」：

一个双时代适配器的骨架如下。关键点不是代码量，而是把「探测」「编解码」「错误映射」三件事分开，别让它们散落在业务逻辑里：

class EraAdapter:
    def __init__(self, transport):
        self.transport = transport
        self.era = None          # "2025" | "2026"

    def detect(self):
        if self.transport == "stdio":
            resp = self.rpc("server/discover", meta=modern_meta())
            if "result" in resp:
                self.era = "2026"
                return self.era
            if resp.get("error", {}).get("code") == -32022:
                # modern server，只是版本不支持：按 supported 选，不回退
                self.era = "2026"
                self.version = pick(resp["error"]["data"]["supported"])
                return self.era
            # 其他错误或超时：legacy
            self.era = "2025"
            self.initialize_legacy()
            return self.era
        # HTTP：先发 modern 请求；400 时先看 body 是否是已知 modern 错误
        resp, status = self.post_modern("tools/list")
        if status == 200:
            self.era = "2026"
        elif is_known_modern_error(resp):
            raise ProtocolError(resp)      # 不要回退
        else:
            self.era = "2025"
            self.initialize_legacy()
        return self.era

    def call_tool(self, name, args):
        if self.era == "2026":
            return self.rpc("tools/call", {"name": name, "arguments": args,
                                           "_meta": modern_meta()})
        return self.rpc("tools/call", {"name": name, "arguments": args})

这段骨架省略了认证、超时与重试，但保留了最重要的分支：modern 错误不触发回退。把 -32022 当成「对方是旧版」是最常见的误判——它恰恰说明对方是新版，只是不支持你请求的版本。

把两个时代跑一遍。 协议细节读到这里，最好的验收是让两版真的跑起来。实验目录里的客户端会启动 server 子进程，逐帧打印，并对关键路径做断言：

python3 experiments/ch02/mcp_client.py --era 2026 --root /tmp/ch02-mcp \
  --trace experiments/ch02/trace-2026.jsonl --quiet
python3 experiments/ch02/mcp_client.py --era 2025 --root /tmp/ch02-mcp \
  --trace experiments/ch02/trace-2025.jsonl --quiet
python3 -m unittest discover -s experiments/ch02 -v

checks: ok=28 fail=0
checks: ok=19 fail=0

28 条断言覆盖 2026 的发现、列表、成功调用、参数错误、未知工具、未知方法、缺元数据、版本不支持、MRTR 往返与 requestState 篡改；19 条覆盖 2025 的握手顺序、ping、资源读取、订阅通知与 legacy 错误码。把请求序列单独抽出来看，能直接读出「哪些帧是正常路径、哪些是负例」：

jq -r 'select(.dir=="send") | [.frame.id, .frame.method] | @tsv' \
  experiments/ch02/trace-2026.jsonl

1	server/discover
2	tools/list
3	tools/call
4	tools/call
5	tools/call
6	tools/call
7	tools/call
8	tools/frobnicate
9	tools/list
10	tools/list
11	tools/call
12	tools/call
13	tools/call
14	tools/call
	notifications/cancelled

读这段输出：id 5、6、7、8、9、10、14 是负例（路径逃逸、类型错误、未知工具、未知方法、缺 _meta、旧版本、篡改状态）；id 11 与 12 是 MRTR 的两轮，必须是两个不同的 id——它们是两次独立请求，第二次带上 inputResponses 与 requestState；最后一行的通知没有 id，因为它不需要响应。正常路径是 1–4 与 12–13，其余都在验证「失败发生在正确的层」。

测试输出（完整；耗时因机器而异）：

test_call_and_legacy_error_code (test_protocol.Test2025.test_call_and_legacy_error_code) ... ok
test_discover_is_unknown_in_2025 (test_protocol.Test2025.test_discover_is_unknown_in_2025) ... ok
test_handshake_is_required (test_protocol.Test2025.test_handshake_is_required) ... ok
test_initialized_notification_is_required (test_protocol.Test2025.test_initialized_notification_is_required) ... ok
test_missing_resource_uses_legacy_code (test_protocol.Test2025.test_missing_resource_uses_legacy_code) ... ok
test_ping_logging_and_resources (test_protocol.Test2025.test_ping_logging_and_resources) ... ok
test_call_success (test_protocol.Test2026.test_call_success) ... ok
test_discover (test_protocol.Test2026.test_discover) ... ok
test_initialize_is_gone (test_protocol.Test2026.test_initialize_is_gone) ... ok
test_input_validation_is_tool_error (test_protocol.Test2026.test_input_validation_is_tool_error) ... ok
test_missing_meta (test_protocol.Test2026.test_missing_meta) ... ok
test_mrtr_request_state_is_integrity_protected (test_protocol.Test2026.test_mrtr_request_state_is_integrity_protected) ... ok
test_mrtr_round_trip (test_protocol.Test2026.test_mrtr_round_trip) ... ok
test_stdout_is_pure_json (test_protocol.Test2026.test_stdout_is_pure_json) ... ok
test_tools_list_is_stable_and_has_schemas (test_protocol.Test2026.test_tools_list_is_stable_and_has_schemas) ... ok
test_unknown_method (test_protocol.Test2026.test_unknown_method) ... ok
test_unknown_tool_is_protocol_error (test_protocol.Test2026.test_unknown_tool_is_protocol_error) ... ok
test_wrong_version (test_protocol.Test2026.test_wrong_version) ... ok
test_client_2025 (test_protocol.TestClientEndToEnd.test_client_2025) ... ok
test_client_2026 (test_protocol.TestClientEndToEnd.test_client_2026) ... ok

----------------------------------------------------------------------
Ran 20 tests in 0.652s

OK

test_stdout_is_pure_json 值得单独说：它把 server 的所有 stdout 行重新 json.loads 一遍，任何一行日志混进来都会失败。这类测试比「功能对不对」更早发现问题，因为它把传输层的硬约束变成了可执行的断言。

母本对应

读这张表要抓住两点：对 OS 与网络只做边界引用，不重复讲信号、管道、TCP 的重传；对协议新增层（schema、function calling、MCP、OAuth 组合）则给到可实现的细节。表中「背景」表示只借用一个概念，正文不展开母本内容。

本章陷阱

这张表说明什么：十二条里，前七条偏「格式与回路」，后五条偏「边界、错误与权限」。它们的共同点是都不会靠换模型消失；换一个更强的模型，只会让越权调用发生得更流畅。第 3、4 章会把第 11、12 条展开成进程、文件、网络与 capability 的具体边界。

本章出口检查

下一站：3 沙箱 把「工具能做什么」收紧为「进程、文件、网络、资源四层边界」，让协议里的授权承诺落到内核能执行的限制上。