---
tags: [AI, mcp, protocol]
阶段: 08-Agent与工程化
难度: ★★★
created: 2026-10-18
related: "[[AI-Agent与工具调用]], [[Harness与Loop工程]], [[结构化输出]]"
---

# MCP协议

## 定义

**模型上下文协议**（Model Context Protocol，MCP）是建立在 JSON-RPC 2.0 之上的应用层协议，它规定宿主应用如何为每个外部能力提供者建立独立连接，如何在连接开始时协商协议版本与能力集合，如何枚举并调用该提供者的工具、资源与提示模板，以及如何用统一的内容块结构返回调用结果。

一次 MCP 会话可记为六元组 $s=(H,C,S,\tau,\pi,\kappa)$。本篇出现的符号如下表，其中 $T,R,P$ 是某个 Server 的能力集合，$id$ 是消息字段。

| 符号 | 含义 |
|---|---|
| $H$ | Host，宿主应用进程，持有模型、用户界面与权限策略 |
| $C$ | Client，Host 内为一个 Server 建立的连接对象，与 Server 一一对应 |
| $S$ | Server，提供工具、资源或提示模板的进程或远程服务 |
| $\tau$ | 传输通道，取 stdio 或 HTTP 两类之一 |
| $\pi$ | 协议版本，形如 `2025-06-18` 的日期字符串 |
| $\kappa=(\kappa_C,\kappa_S)$ | 握手后双方各自声明并接受的能力集合 |
| $T,R,P$ | 某个 Server 的工具集合、资源集合、提示模板集合 |
| $id$ | JSON-RPC 请求标识，同一会话内唯一，用于匹配响应 |

术语按首次出现处定义：**工具**（tool）是 Server 暴露的可执行函数，具有名称、说明与输入模式；**资源**（resource）是可由 URI 定位的只读上下文数据；**提示模板**（prompt）是带参数的、可复用的消息序列；**能力**（capability）是双方在 `initialize` 中声明的功能集合，声明后才允许使用对应方法；**内容块**（content block）是工具结果与消息内容的基本单元，`type` 取 `text`、`image`、`audio`、`resource_link` 或 `resource`；**通知**（notification）是无 `id`、不要求回复的 JSON-RPC 消息。

协议版本是日期字符串，版本之间可以增删字段。本篇以 `2025-06-18` 版为准；该版的三个部分，即 JSON-RPC 消息层、`initialize` 握手、三类原语，在前后版本中保持稳定。

## 为什么重要

集成成本随宿主应用数与能力提供者数的乘积增长。设宿主应用有 $M$ 种、能力提供者有 $N$ 种，若每对组合都需要专门适配，需要实现的适配器数量为

$$
A_{\text{ad-hoc}}=M\cdot N ,
$$

而协议化之后，每一侧只需实现一次协议，适配器数量降为

$$
A_{\text{proto}}=M+N .
$$

取 $M=8$、$N=20$，前者为 160，后者为 28。该对比只统计传输、序列化、能力发现、生命周期与错误格式的复用；它不减少语义映射的工作量，因为每个 Server 仍必须定义自己的工具语义与输入模式。把 $M+N$ 理解为"所有集成都变简单"是过度推断，正确的结论是：重复的工程部分被收敛到协议层，剩下的部分按 Server 计一次。

没有协议会产生四类具体后果。第一类是发现成本：宿主无法在运行时知道某个数据源提供哪些能力，工具清单必须硬编码并随提供者升级重新发版。第二类是权限成本：每个适配器自行决定何时请求用户同意，同意粒度、展示内容与撤销方式各不相同，无法审计。第三类是生命周期成本：连接建立、版本不匹配、进程崩溃、请求取消各自实现一套，边界情况覆盖不全。第四类是组合成本：一个宿主连接多个提供者时，工具重名、错误码冲突、超时语义不一致没有统一的解决位置。

MCP 在本库中的位置是能力层。[[AI-Agent与工具调用]] 讨论单次工具调用的模式与回填，[[结构化输出]] 讨论输入模式所用的 JSON Schema 语义，本篇讨论这些能力如何跨进程被发现与调用；[[Harness与Loop工程]] 则把 Client 视为工具执行层的一个后端，在其上实现循环、预算与轨迹。对应学习目标中的"能复现"与"会评估"：能写出一个可被宿主加载的 Server，能判断一次失败发生在传输层、协议层还是工具执行层。

## 原理与推导

### 1 三个角色与连接拓扑

三个角色的职责边界由一条不变量确定：Server 不能直接访问模型，Server 之间互不可见，只有 Host 同时持有模型输出与全部连接。由此可以确定三个角色各自的职责范围。

Host 的职责有四项：维护会话与模型调用；为每个 Server 创建并维护一个 Client；聚合所有 Server 的能力清单并处理命名冲突；在执行前完成权限检查与用户同意。Client 的职责是连接级的：编解码、分配请求 `id`、匹配响应与通知、维护该连接的生命周期状态。Server 的职责是能力级的：声明能力、响应枚举与调用、主动发送变更通知；需要模型或文件系统边界时，通过反向请求 `sampling/createMessage` 或 `roots/list` 向 Client 索取。

```mermaid
flowchart LR
    U[用户] --> H[Host 宿主应用]
    H --> C1[Client 1]
    H --> C2[Client 2]
    C1 <-->|stdio| S1[Server 文件系统]
    C2 <-->|HTTP+SSE| S2[Server 数据库]
```

一次工具调用的消息序列如下。注意 `notifications/initialized` 没有响应，Client 发送后不等待。

```mermaid
sequenceDiagram
    participant H as Host
    participant C as Client
    participant S as Server
    participant M as 模型
    C->>S: initialize(protocolVersion, capabilities)
    S-->>C: result(protocolVersion, capabilities, serverInfo)
    C->>S: notifications/initialized
    C->>S: tools/list
    S-->>C: result(tools[...])
    H->>M: 请求(含工具清单)
    M-->>H: 调用意图 add(a=19, b=23)
    H->>H: 权限检查与用户同意
    H->>C: tools/call
    C->>S: tools/call(name, arguments)
    S-->>C: result(content, isError)
    H->>M: 回填工具结果
```

命名空间是聚合的直接结果。两个 Server 都可能提供名为 `search` 的工具，Host 必须为每个工具生成唯一标识，例如 `serverA.search` 与 `serverB.search`，并在把调用意图发回模型之前完成反向映射。若不做这一步，后注册的工具会覆盖先注册的工具，表现为"模型调用了错误的实现"。

### 2 传输层

传输层只负责消息边界，不负责重试与顺序。消息按行分隔，每条消息占一行，请求与响应通过 `id` 关联，因此同一连接上可以有多个未完成请求，响应可以乱序到达。

stdio 的规则如下。Host 以子进程方式启动 Server，Server 从标准输入读取消息、向标准输出写出消息，标准错误用于日志。每条消息是一行 UTF-8 编码的 JSON，以 `\n` 结束，JSON 字符串内部的换行必须转义，否则会被拆成两条消息。stdio 没有内建认证，Server 以宿主用户的权限运行，安全边界由操作系统提供。会话结束时 Host 关闭子进程的标准输入，Server 读到 EOF 后退出；Host 应设置退出等待上限，超时后终止进程。

stdio 适用于本地能力：文件系统、本地数据库、命令行工具、需要读取用户机器状态的服务。它不适用于多租户共享或需要独立扩缩容的场景，因为每个用户都需要一个进程，权限与配额无法在协议层区分。

HTTP 传输有两代，差异在端点数量与会话标识。下表对比三者。

| 维度 | stdio | HTTP+SSE（2024-11-05） | Streamable HTTP（2025-03-26 起） |
|---|---|---|---|
| 端点 | 子进程的 stdin/stdout | 两个：GET 事件流端点与 POST 消息端点 | 一个：POST 与 GET 使用同一 URL |
| 客户端到服务端 | 写入 stdin，每行一条 JSON | POST 到消息端点，返回 202 | POST 单条消息，响应为 JSON 或 SSE |
| 服务端到客户端 | 写入 stdout | GET 建立的 SSE 流 | POST 的 SSE 响应，或独立的 GET 流 |
| 认证 | 无，依赖进程权限 | 规范未定义，部署方自定 | OAuth 2.1 持有者令牌 |
| 会话标识 | 进程本身 | 无标准头 | `Mcp-Session-Id` 响应头 |
| 断线恢复 | 无，进程退出即结束 | 需重新建立两条连接 | `Last-Event-ID` 续传 |
| 适用 | 本地工具、文件、CLI | 兼容旧实现 | 远程共享服务、多租户、集中审计 |
| 主要风险 | 任意本地代码执行 | 连接关联困难 | DNS 重绑定、会话劫持、混淆代理 |

Streamable HTTP 的协议细节包括：服务端若分配会话，在 `initialize` 的响应中通过 `Mcp-Session-Id` 头返回，后续请求必须携带该头；客户端在后续请求中携带 `MCP-Protocol-Version` 头声明版本；服务端对不存在的会话返回 404，客户端必须重新握手；服务端不支持 GET 流时返回 405；事件流中的消息带 `id` 字段，客户端用 `Last-Event-ID` 请求续传。远程部署还必须校验 `Origin` 头、在本地部署时绑定回环地址、在公网部署时启用 TLS，否则浏览器页面可以借助用户的本机连接发起跨站请求。

### 3 JSON-RPC 2.0 消息格式

MCP 的全部消息都是 JSON-RPC 2.0 对象，共三种。

请求携带 `id`、`method`、`params`，接收方必须回复一条 `id` 相同的响应：

```json
{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {"name": "add", "arguments": {"a": 19, "b": 23}}}
```

成功响应只含 `result`，失败响应只含 `error`，二者互斥：

```json
{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "{\"sum\": 42}"}], "isError": false}}
```

```json
{"jsonrpc": "2.0", "id": 1, "error": {"code": -32602, "message": "Invalid params",
 "data": {"field": "arguments.a"}}}
```

通知没有 `id`，接收方不得回复。MCP 的通知方法名统一以 `notifications/` 为前缀：

```json
{"jsonrpc": "2.0", "method": "notifications/initialized"}
```

规则可以归纳为八条。第一，`jsonrpc` 字段固定为字符串 `"2.0"`。第二，请求的 `id` 必须存在且不为 `null`，取字符串或数字，同一会话内不得复用尚未完成的 `id`。第三，`id` 是匹配响应的唯一依据，Host 必须维护 `id` 到连接、方法名与截止时间的映射表。第四，响应必须有且只有一个 `result` 或 `error`。第五，通知没有 `id`，不得回复，也不参与 `id` 映射。第六，`params` 为对象，MCP 全部使用具名参数。第七，JSON-RPC 允许把多条消息打包为数组，MCP 在 `2025-03-26` 版允许批量请求，在 `2025-06-18` 版移除，因此实现不得依赖批量。第八，JSON-RPC 不保证响应顺序，也不要求请求串行，实现必须容忍乱序与并发。

### 4 初始化握手与能力协商

握手由三条消息构成，缺一不可。

```json
{"jsonrpc": "2.0", "id": 1, "method": "initialize",
 "params": {
   "protocolVersion": "2025-06-18",
   "capabilities": {"roots": {"listChanged": true}, "sampling": {}},
   "clientInfo": {"name": "example-host", "version": "0.1.0"}}}
```

```json
{"jsonrpc": "2.0", "id": 1, "result": {
  "protocolVersion": "2025-06-18",
  "capabilities": {"tools": {"listChanged": true},
                   "resources": {"subscribe": true, "listChanged": true}},
  "serverInfo": {"name": "example-server", "version": "1.4.2"},
  "instructions": "文件系统中的笔记可通过 resources 读取。"}}
```

```json
{"jsonrpc": "2.0", "method": "notifications/initialized"}
```

版本协商按以下步骤执行。第一步，Client 发送自己支持的最新版本 $\pi_C$。第二步，Server 若支持 $\pi_C$ 则原样返回，否则返回自己支持的一个版本 $\pi_S$。第三步，Client 检查 $\pi_S$ 是否在自己支持的集合内，不支持则断开连接，不得按未声明版本继续通信。第四步，双方按对方声明的能力集合决定可用方法，未声明能力对应的方法不得调用。第五步，Client 发送 `notifications/initialized`，会话进入正常阶段。

能力集合的内容如下表。`listChanged` 表示该集合变化时会发送通知，Host 收到后必须重新枚举。

| 方向 | 能力 | 附加字段 | 对应方法与通知 |
|---|---|---|---|
| Client | `roots` | `listChanged` | `roots/list`、`notifications/roots/list_changed` |
| Client | `sampling` | 无 | `sampling/createMessage` |
| Client | `elicitation` | 无 | `elicitation/create` |
| Server | `tools` | `listChanged` | `tools/list`、`tools/call`、`notifications/tools/list_changed` |
| Server | `resources` | `subscribe`、`listChanged` | `resources/list`、`resources/templates/list`、`resources/read`、`resources/subscribe` |
| Server | `prompts` | `listChanged` | `prompts/list`、`prompts/get`、`notifications/prompts/list_changed` |
| Server | `logging` | 无 | `logging/setLevel`、`notifications/message` |
| Server | `completions` | 无 | `completion/complete` |

三条时序规则决定握手阶段的行为边界。`initialize` 在每个会话中只能发送一次，重复发送属于非法请求。Client 在收到 `initialize` 响应之前只应发送 `ping`，其余请求应等待。Server 在收到 `notifications/initialized` 之前只应发送 `ping` 与日志消息，不得主动发起其他请求。

能力声明的工程后果是界面不能静态绑定功能。Host 只有在握手完成后才知道某个 Server 是否提供资源，因此资源面板、工具菜单与审批界面都必须在握手后按能力集合动态生成；把 `resources` 写死在界面里，在连接只提供工具的 Server 时会产生空面板与无效调用。

### 5 工具原语

工具由模型选择调用，这是它与资源、提示模板在控制权上的根本差异。`tools/list` 返回工具数组，每个工具对象包含名称、可选标题、说明、输入模式与行为提示。

```json
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}
```

```json
{"jsonrpc": "2.0", "id": 2, "result": {"tools": [{
  "name": "add",
  "title": "两数相加",
  "description": "返回两个数字 a 与 b 的和，结果绝对值不得超过 1000。",
  "inputSchema": {
    "type": "object",
    "properties": {"a": {"type": "number"}, "b": {"type": "number"}},
    "required": ["a", "b"],
    "additionalProperties": false},
  "outputSchema": {"type": "object",
                   "properties": {"sum": {"type": "number"}},
                   "required": ["sum"]},
  "annotations": {"readOnlyHint": true, "destructiveHint": false,
                  "idempotentHint": true, "openWorldHint": false}}]}}
```

`inputSchema` 是 JSON Schema 对象，默认值为 `{"type": "object"}`。`outputSchema` 在 `2025-06-18` 版加入，用于声明 `structuredContent` 的结构；声明了输出模式的工具应当同时在 `content` 中返回序列化后的 JSON 文本，以兼容只读取文本内容的客户端。`annotations` 是行为提示，`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint` 均不具强制性，Host 必须自行判断是否需要用户确认。

调用与结果如下。结果中的 `content` 是内容块数组，`isError` 标记工具执行是否失败。

```json
{"jsonrpc": "2.0", "id": 3, "method": "tools/call",
 "params": {"name": "add", "arguments": {"a": 19, "b": 23}}}
```

```json
{"jsonrpc": "2.0", "id": 3, "result": {
  "content": [{"type": "text", "text": "{\"sum\": 42}"}],
  "structuredContent": {"sum": 42},
  "isError": false}}
```

内容块类型与必填字段如下表。

| `type` | 必填字段 | 用途 |
|---|---|---|
| `text` | `text` | 纯文本结果 |
| `image` | `data`、`mimeType` | base64 编码图像 |
| `audio` | `data`、`mimeType` | base64 编码音频 |
| `resource_link` | `uri`、`name` | 引用资源，不内联内容 |
| `resource` | `resource` 对象，含 `uri` 与 `text` 或 `blob` | 内联资源内容 |

错误分两个通道，分工必须明确。参数不符合 `inputSchema`、工具名不存在、方法未实现属于协议层错误，用 JSON-RPC `error` 返回，因为这类错误说明调用方与 Server 的约定不一致，模型无法通过重试修正。工具已执行但业务失败，例如目标不存在、下游服务拒绝、输入超出业务范围，用 `result` 加 `isError: true` 返回，并在 `content` 中给出可读原因，使模型能够修改参数后重试。把业务错误放进 JSON-RPC `error` 会让模型看不到原因，把协议错误放进 `isError` 会让 Host 误以为工具存在。

工具名是跨 Server 的全局命名空间问题。规范建议名称为 1 至 128 个字符，只含字母、数字、下划线、连字符与点，且区分大小写。Host 聚合多个 Server 时应加前缀，并在工具定义变化时使旧批准失效。

### 6 资源原语

资源由应用控制，Host 决定哪些资源进入上下文，模型不直接读取。`resources/list` 返回资源描述，`resources/read` 按 URI 读取内容。

```json
{"jsonrpc": "2.0", "id": 4, "method": "resources/list"}
```

```json
{"jsonrpc": "2.0", "id": 4, "result": {"resources": [{
  "uri": "file:///notes/08/MCP%E5%8D%8F%E8%AE%AE.md",
  "name": "MCP协议.md",
  "mimeType": "text/markdown",
  "annotations": {"audience": ["assistant"], "priority": 0.8,
                  "lastModified": "2026-10-18T12:00:00Z"}}]}}
```

模板用于描述一族 URI，参数按 RFC 6570 展开。`resources/templates/list` 返回模板，Host 在用户选择具体参数后调用 `resources/read`。

```json
{"jsonrpc": "2.0", "id": 5, "method": "resources/templates/list"}
```

```json
{"jsonrpc": "2.0", "id": 5, "result": {"resourceTemplates": [{
  "uriTemplate": "file:///notes/{stage}/{name}.md",
  "name": "笔记",
  "mimeType": "text/markdown"}]}}
```

读取结果是一个 `contents` 数组，每项含 `uri`、可选 `mimeType`，以及 `text` 或 `blob` 之一。URI 不存在时返回错误码 `-32002`。资源支持订阅：Client 发送 `resources/subscribe` 后，Server 在内容变化时发送 `notifications/resources/updated`，其参数包含变化的 `uri`；资源集合本身变化时发送 `notifications/resources/list_changed`。

资源与工具的分工可以用一次往返是否必要来判断。只读且 Host 能预先确定需要的上下文，应当在构造消息时直接读取并注入，省去一次模型决策与工具往返；需要模型根据中间结果决定读什么，才应包装为工具。资源的代价是 Host 必须理解 URI 语义并处理注入内容，工具结果与资源内容在安全性上没有区别，两者都可能携带提示注入。

### 7 提示原语

提示模板由用户控制，典型形态是斜杠命令或模板菜单。`prompts/list` 返回模板及其参数，`prompts/get` 按名称与参数展开为消息序列。

```json
{"jsonrpc": "2.0", "id": 6, "method": "prompts/list"}
```

```json
{"jsonrpc": "2.0", "id": 6, "result": {"prompts": [{
  "name": "review-note",
  "title": "审查笔记",
  "description": "按规范检查一篇笔记的结构与链接。",
  "arguments": [{"name": "path", "description": "笔记路径", "required": true}]}]}}
```

```json
{"jsonrpc": "2.0", "id": 7, "method": "prompts/get",
 "params": {"name": "review-note", "arguments": {"path": "08-Agent与工程化/MCP协议.md"}}}
```

```json
{"jsonrpc": "2.0", "id": 7, "result": {
  "description": "审查笔记",
  "messages": [{"role": "user",
    "content": {"type": "text", "text": "检查 08-Agent与工程化/MCP协议.md 的结构。"}}]}}
```

模板参数由 Host 或用户填充，不由模型生成，这与工具参数的控制方相反。三类原语的差异汇总如下。

| 原语 | 控制方 | 发现方法 | 调用方法 | 结果是否进入模型上下文 |
|---|---|---|---|---|
| 工具 | 模型 | `tools/list` | `tools/call` | 是 |
| 资源 | 应用 | `resources/list`、`resources/templates/list` | `resources/read` | 由应用决定 |
| 提示模板 | 用户 | `prompts/list` | `prompts/get` | 是，展开为消息 |

### 8 采样与根

采样让 Server 借用 Host 的模型，从而不必自带上游 API 密钥。方向是 Server 到 Client 的请求：

```json
{"jsonrpc": "2.0", "id": 8, "method": "sampling/createMessage",
 "params": {
   "messages": [{"role": "user", "content": {"type": "text", "text": "概括这段日志。"}}],
   "modelPreferences": {"hints": [{"name": "claude"}],
                        "costPriority": 0.3, "speedPriority": 0.2,
                        "intelligencePriority": 0.5},
   "systemPrompt": "只输出中文摘要。",
   "includeContext": "none",
   "maxTokens": 256,
   "temperature": 0.2}}
```

结果包含 `role`、`content`、`model` 与 `stopReason`。`modelPreferences` 是偏好而非指定，最终模型由 Host 选择。`includeContext` 取 `none`、`thisServer` 或 `allServers`，取 `allServers` 时 Host 会把其他 Server 的上下文提供给模型，这会造成跨信任域的数据泄露，默认应取 `none` 或 `thisServer`。规范要求采样请求应保留人工审查与拒绝的能力。

根用于声明文件系统边界。Client 收到 Server 的 `roots/list` 请求后返回根目录列表：

```json
{"jsonrpc": "2.0", "id": 9, "result": {"roots": [
  {"uri": "file:///D:/DSH_Workspace/AIlearning", "name": "AIlearning"}]}}
```

根发生变化时 Client 发送 `notifications/roots/list_changed`。根是建议性边界，不是访问控制：Server 必须自行做路径规范化与前缀校验，否则 `file:///root/../etc/passwd` 这类路径可以逃逸。把根当作沙箱使用是集成阶段的高危错误。

### 9 生命周期、取消、进度与超时

会话状态可以划分为四个阶段。

| 状态 | 允许的消息 | 迁移条件 |
|---|---|---|
| 未初始化 | `initialize`、`ping` | 收到 `initialize` 请求 |
| 握手中 | `initialize` 响应、`notifications/initialized`、`ping` | 收到 `notifications/initialized` |
| 就绪 | 全部已声明能力对应的方法 | 传输关闭或致命错误 |
| 关闭 | 无 | 进程退出或连接释放 |

`ping` 可由任一方发送，响应为空结果，用于探活。

取消是协作式的通知：请求方发送 `notifications/cancelled`，参数包含待取消请求的 `requestId` 与可选 `reason`；接收方应停止处理并释放资源，且不得再为该请求发送响应；若响应已经发出，发送方应忽略。`initialize` 不得被取消，因为版本与能力协商失败会使整个会话失去语义。取消无法撤销已经发生的副作用，也无法强制中断不可抢占的工具执行，因此 Host 仍必须在执行层设置硬超时。

进度用于长任务。请求在 `params._meta.progressToken` 中携带令牌，接收方发送 `notifications/progress`，参数含 `progressToken`、累计的 `progress`、可选 `total` 与 `message`。`progress` 是累计值而非增量，重复的令牌对应同一个任务。

协议不规定超时时长。Host 应为每个请求设置截止时间，超时后发送取消通知、丢弃迟到响应、释放 `id` 映射，并把该步骤标记为超时；Server 应把截止时间传递给下游调用，否则 Host 已经放弃而 Server 仍在消耗资源。

会话结束没有专门的关闭方法。stdio 下 Host 关闭标准输入，Server 读到 EOF 后退出，Host 等待退出，超时后终止进程；HTTP 下 Host 终止会话或关闭事件流，服务端清理会话状态。

### 10 错误模型

错误分布在三层，处理方式不同。

| 层 | 表现 | 典型原因 | 处理 |
|---|---|---|---|
| 传输层 | 连接断开、JSON 解析失败 | 日志写入标准输出、编码不一致 | 终止会话、记录原始字节、修正 Server |
| 协议层 | JSON-RPC `error` 对象 | 参数不合法、方法不存在、未初始化 | 转为失败步骤，不自动重试 |
| 执行层 | `result.isError` 为真 | 下游超时、目标不存在、权限不足 | 可重试、回填模型修正、终止 |

JSON-RPC 与 MCP 使用的错误码如下表。

| 码 | 名称 | 触发条件 |
|---|---|---|
| `-32700` | Parse error | 收到非 JSON 文本 |
| `-32600` | Invalid Request | 缺少必需字段、`id` 非法、消息不是合法请求 |
| `-32601` | Method not found | 方法未实现 |
| `-32602` | Invalid params | 参数不符合模式、工具名不存在 |
| `-32603` | Internal error | 服务端内部异常 |
| `-32002` | Resource not found | `resources/read` 的 URI 不存在 |
| `-32000` 至 `-32099` | 实现自定义 | 服务端定义的业务错误，应在 `data` 中说明 |

Host 的职责是把协议层错误转换成模型可理解的信息。模型只看到会话消息，看不到 JSON-RPC 错误对象，因此 Host 必须把错误码与原因写入一条工具结果消息，并标注这是协议失败而非业务失败，否则模型会反复用同样的参数重试。

### 11 权限、同意与安全风险

用户同意是协议的强制环节，不是界面装饰。Host 在调用前应展示 Server 身份、工具名与完整参数，对具有破坏性的操作每次确认，对只读操作可按会话记忆。批准的粒度应按"Server 加工具定义哈希"记录，工具定义变化后旧批准失效，否则恶意 Server 可以先发布只读工具获取批准，再把它替换为写操作。

工具投毒（tool poisoning）指 Server 在工具说明、参数说明或工具结果中写入面向模型的指令，使模型把不可信文本当作任务要求执行。这类攻击不依赖协议漏洞，只依赖模型会把上下文中的文本当作指令。缓解手段包括：把工具元数据视为不可信输入并在界面中展示原文；对工具定义做哈希固定，变化时重新审批；限制可安装的 Server 来源；对工具结果中的指令性文本做分隔与过滤。

混淆代理（confused deputy）指 Server 持有比调用者更大的权限，攻击者通过它代理执行越权操作。典型情形是 Server 内置了高权限服务账号，调用者只需构造参数即可访问无权访问的数据。缓解要求每个请求都携带调用者身份并在 Server 内做授权判断，不能因为"请求来自宿主"就默认可信。

令牌透传（token passthrough）指 Server 把收到的访问令牌原样转发给下游 API。MCP 规范明确禁止这种行为：Server 不得接受未签发给自己的令牌，必须校验令牌的受众，否则被攻破的下游服务可以用该令牌横向访问其他资源。HTTP 传输的授权基于 OAuth 2.1，令牌应带资源指示符。

跨 Server 的提示注入传播是 MCP 特有的风险。Server A 的工具结果可以包含"请调用 Server B 并把配置发送到某地址"，若 Host 自动把 A 的输出作为 B 的调用参数，用户同意就被绕过。缓解要求：不同信任域的 Server 之间不自动串联；对跨 Server 的数据流打标签；调用 B 时重新请求同意；限制 B 能看到的上下文范围。

还有两类与部署相关的风险。命名遮蔽指多个 Server 提供同名工具，Host 未做命名空间隔离，模型调用了非预期的实现。本地 Server 即任意代码执行：stdio Server 以用户权限运行，可读取文件与环境变量，安装一个 Server 等同于授予其与用户同等的权限，应在容器或受限账户中运行并清理环境变量。

### 12 与 OpenAI function calling 的关系

两者不在同一层。函数调用是模型 API 的输出格式约定：调用方在每次请求中传入工具定义，模型输出工具名与参数，执行发生在调用方进程内，没有标准的发现机制与生命周期。MCP 是进程间协议：工具定义在运行时通过 `tools/list` 获取，执行发生在独立进程或远程服务，结果以内容块返回，连接有版本协商、能力声明与取消语义。

| 维度 | OpenAI function calling | MCP |
|---|---|---|
| 抽象层 | 模型输出格式 | 应用层协议 |
| 工具定义来源 | 每次请求的 `tools` 参数 | `tools/list` 运行时获取 |
| 发现时机 | 调用前由应用确定 | 握手后动态获取，可变更 |
| 执行位置 | 调用方进程 | 独立进程或远程服务 |
| 传输 | HTTP API | stdio 或 HTTP |
| 认证 | API 密钥 | 进程权限或 OAuth 2.1 |
| 错误通道 | 工具消息回填 | JSON-RPC `error` 与 `isError` 两种 |
| 多来源 | 应用自行聚合 | Host 聚合多个 Client |

二者的组合方式是上下游关系。Host 把 `tools/list` 的结果转换为模型 API 的 `tools` 参数，把模型返回的调用意图转换为 `tools/call`。转换时需要注意模式方言差异：函数调用的严格模式通常要求对象模式声明 `additionalProperties: false`、所有属性列入 `required`、可选字段用联合类型表达 `null`，而 MCP 的 `inputSchema` 是完整的 JSON Schema，直接透传可能被模型 API 拒绝。转换层必须做子集裁剪与校验，且裁剪后的模式要与 Server 端的校验保持一致，否则会出现"模型生成的参数被 API 接受但被 Server 拒绝"的错位。

## 关键直觉

> [!tip] 机制性表述
> MCP 把能力发现与能力调用固定为 `tools/list` 与 `tools/call` 两类消息，因此 Host 在编译期不需要知道任何 Server 的存在；握手完成后，Server 的能力集合成为一个可枚举的运行时对象，Host 对它的处理与本地函数表相同。协议保证的是消息形状、状态迁移与错误通道，不保证能力语义，语义仍由每个 Server 的模式与文档定义。
>
> 与定义的关系：定义中的"统一的消息格式"对应这三类消息与内容块，"能力协商"对应 `initialize` 的 `capabilities` 字段，"权限边界"对应 Host 作为唯一同时看见模型输出与全部连接的位置。由此可以推出，所有跨 Server 的安全决策只能在 Host 完成，Server 只能约束自己的输出。

## 例子与代码

### 例 1：最小 MCP server

下面是一个完整的 stdio Server，只依赖 Python 标准库，实现 `initialize`、`tools/list`、`tools/call` 三个方法与 `notifications/initialized` 通知。环境为 Python 3.10 及以上，实测 3.12。

```python
#!/usr/bin/env python3
"""最小 MCP server（Python 3.10+，仅标准库）：stdio 传输，暴露一个 add 工具。"""

import json
import sys

PROTOCOL_VERSION = "2025-06-18"
SERVER_INFO = {"name": "minimal-adder", "version": "0.1.0"}

TOOLS = [
    {
        "name": "add",
        "title": "两数相加",
        "description": "返回两个数字 a 与 b 的和，结果绝对值不得超过 1000。",
        "inputSchema": {
            "type": "object",
            "properties": {"a": {"type": "number"}, "b": {"type": "number"}},
            "required": ["a", "b"],
            "additionalProperties": False,
        },
        "annotations": {"readOnlyHint": True, "destructiveHint": False,
                        "idempotentHint": True, "openWorldHint": False},
    }
]


def log(text):
    """日志写入 stderr；stdout 由协议独占。"""
    print(f"[minimal-adder] {text}", file=sys.stderr, flush=True)


def response(req_id, result):
    return {"jsonrpc": "2.0", "id": req_id, "result": result}


def error(req_id, code, message):
    return {"jsonrpc": "2.0", "id": req_id, "error": {"code": code, "message": message}}


def run_add(arguments):
    """执行工具；参数类型错误抛 ValueError，业务限制用 isError 返回。"""
    values = {}
    for name in ("a", "b"):
        value = arguments.get(name)
        if isinstance(value, bool) or not isinstance(value, (int, float)):
            raise ValueError(f"参数 {name} 必须是数字")
        values[name] = value
    total = values["a"] + values["b"]
    if abs(total) > 1000:
        return {"content": [{"type": "text", "text": f"结果 {total} 超出上限 1000"}],
                "isError": True}
    return {"content": [{"type": "text", "text": json.dumps({"sum": total})}],
            "structuredContent": {"sum": total},
            "isError": False}


def handle(message, state):
    """处理一条 JSON-RPC 消息，返回待写出的消息列表。"""
    method = message.get("method")
    req_id = message.get("id")
    if "id" not in message:                      # 通知：不产生响应
        if method == "notifications/initialized":
            state["initialized"] = True
            log("会话就绪")
        return []

    if method == "initialize":
        return [response(req_id, {
            "protocolVersion": PROTOCOL_VERSION,
            "capabilities": {"tools": {"listChanged": False}},
            "serverInfo": SERVER_INFO,
            "instructions": "使用 add 计算两数之和。",
        })]

    if method == "ping":
        return [response(req_id, {})]

    if not state["initialized"]:
        return [error(req_id, -32600, "请求必须在 initialized 通知之后发送")]

    if method == "tools/list":
        return [response(req_id, {"tools": TOOLS})]

    if method == "tools/call":
        params = message.get("params") or {}
        if params.get("name") != "add":
            return [error(req_id, -32602, f"未知工具：{params.get('name')}")]
        try:
            return [response(req_id, run_add(params.get("arguments") or {}))]
        except ValueError as exc:                # 参数不符合模式：协议层错误
            return [error(req_id, -32602, str(exc))]

    return [error(req_id, -32601, f"方法不存在：{method}")]


def main():
    # stdio 传输固定 UTF-8；Windows 默认使用本地代码页，不显式设置会解码失败。
    sys.stdin.reconfigure(encoding="utf-8")
    sys.stdout.reconfigure(encoding="utf-8", newline="\n")
    sys.stderr.reconfigure(encoding="utf-8")
    state = {"initialized": False}
    log(f"启动，协议版本 {PROTOCOL_VERSION}")
    while True:
        line = sys.stdin.readline()
        if not line:                             # stdin 关闭：宿主结束会话
            break
        line = line.strip()
        if not line:
            continue
        try:
            message = json.loads(line)
        except json.JSONDecodeError:
            sys.stdout.write(json.dumps(
                {"jsonrpc": "2.0", "id": None,
                 "error": {"code": -32700, "message": "JSON 解析失败"}},
                ensure_ascii=False) + "\n")
            sys.stdout.flush()
            continue
        for outgoing in handle(message, state):
            sys.stdout.write(json.dumps(outgoing, ensure_ascii=False) + "\n")
        sys.stdout.flush()                       # 每条响应后立即刷新
    log("stdin 关闭，退出")


if __name__ == "__main__":
    main()
```

逐行解释如下，行号与上列代码块一致。

| 行号 | 代码 | 作用 |
|---|---|---|
| 1–2 | 文件头与模块说明 | 声明用途与依赖，不参与协议 |
| 4–5 | `import json, sys` | 只用标准库，避免宿主安装第三方包 |
| 7–8 | `PROTOCOL_VERSION`、`SERVER_INFO` | 版本与身份，`initialize` 结果使用 |
| 10–24 | `TOOLS` | 工具清单，`tools/list` 原样返回，不在每次调用时重建 |
| 27–29 | `log` | 日志固定写 `stderr`，`flush=True` 保证崩溃前日志落盘 |
| 32–37 | `response`、`error` | 封装 `result` 与 `error` 两种互斥响应，避免手写 `jsonrpc` 字段 |
| 40–54 | `run_add` | 类型校验与结果构造；类型错误抛异常，业务限制走 `isError` |
| 45–46 | 类型校验 | 布尔值是 `int` 子类，必须先排除；不合法抛 `ValueError` |
| 49–51 | 业务限制 | 结果超出上限属于执行失败，走结果通道 |
| 52–54 | 成功结果 | 同时返回文本与 `structuredContent`，兼容只读文本的客户端 |
| 57–65 | 通知分支 | 先判断 `id` 是否存在，通知不产生任何响应 |
| 62–64 | `initialized` 处理 | 记录会话状态，初始化检查在此通过 |
| 67–73 | `initialize` | 返回版本、能力、身份与说明；能力只声明 `tools` |
| 75–76 | `ping` | 返回空结果，探活可用 |
| 78–79 | 初始化检查 | 握手前请求返回 `-32600`，阻止未协商即调用 |
| 81–82 | `tools/list` | 返回静态清单，无分页 |
| 84–91 | `tools/call` | 未知工具与参数错误都返回 `-32602` |
| 86–87 | 未知工具 | 工具名不匹配，协议层错误 |
| 88–91 | 参数异常转换 | `ValueError` 转为 `-32602`，模型无法据此修正 |
| 93 | 兜底 | 未实现方法返回 `-32601` |
| 96–102 | `main` 初始化 | 三处 `reconfigure` 固定 UTF-8 与换行 |
| 98–100 | 编码设置 | Windows 默认代码页为 GBK，不设置会在父进程解码时报错 |
| 103–109 | 读循环 | 用 `readline` 逐行读取；EOF 表示宿主关闭会话 |
| 110–118 | 解析失败 | 返回 `-32700`，此时 `id` 未知，置为 `null` |
| 119–121 | 写出与刷新 | 每条响应后 `flush`，否则父进程会阻塞等待 |
| 122 | 退出日志 | 记录正常关闭，便于区分崩溃 |
| 125–126 | 入口 | 仅在直接运行时启动，便于导入测试 |

三个设计点需要强调。第一，`stdout` 只写协议消息，任何 `print` 调试语句都会破坏 JSON-RPC 帧，因此 `log` 固定写 `stderr`。第二，业务错误与协议错误分开，前者让模型看到原因，后者让 Host 判断集成是否正确。第三，刷新与编码必须显式设置，缓冲与代码页是 stdio 传输最常见的两个故障源。

### 例 2：最小 client 的请求序列

下面的 Client 启动上例的 Server，依次发送 `initialize`、`notifications/initialized`、`tools/list` 与三次 `tools/call`，并在结束时关闭标准输入。

```python
#!/usr/bin/env python3
"""最小 MCP client（仅标准库）：启动 server，按顺序发送四类消息。"""

import json
import subprocess
import sys

SERVER = [sys.executable, "mcp_server.py"]


class Client:
    def __init__(self, command):
        self.proc = subprocess.Popen(command, stdin=subprocess.PIPE,
                                     stdout=subprocess.PIPE, text=True,
                                     encoding="utf-8", bufsize=1)
        self.next_id = 1

    def send(self, payload):
        self.proc.stdin.write(json.dumps(payload, ensure_ascii=False) + "\n")
        self.proc.stdin.flush()                  # 不刷新则 server 收不到

    def request(self, method, params=None):
        req_id = self.next_id
        self.next_id += 1
        payload = {"jsonrpc": "2.0", "id": req_id, "method": method}
        if params is not None:
            payload["params"] = params
        self.send(payload)
        while True:                              # 按 id 匹配响应，跳过不相关消息
            line = self.proc.stdout.readline()
            if not line:
                raise RuntimeError("server 已关闭")
            message = json.loads(line)
            if message.get("id") == req_id:
                return message

    def notify(self, method):
        self.send({"jsonrpc": "2.0", "method": method})


client = Client(SERVER)
init = client.request("initialize", {
    "protocolVersion": "2025-06-18",
    "capabilities": {"roots": {"listChanged": True}},
    "clientInfo": {"name": "minimal-client", "version": "0.1.0"},
})
print("initialize ->", json.dumps(init["result"], ensure_ascii=False))
client.notify("notifications/initialized")
tools = client.request("tools/list")
print("tools/list ->", json.dumps(tools["result"], ensure_ascii=False))
call = client.request("tools/call", {"name": "add", "arguments": {"a": 19, "b": 23}})
print("tools/call ->", json.dumps(call["result"], ensure_ascii=False))
big = client.request("tools/call", {"name": "add", "arguments": {"a": 900, "b": 200}})
print("超上限 ->", json.dumps(big["result"], ensure_ascii=False))
bad = client.request("tools/call", {"name": "add", "arguments": {"a": "19", "b": 23}})
print("坏参数 ->", json.dumps(bad["error"], ensure_ascii=False))
unknown = client.request("tools/call", {"name": "sub", "arguments": {}})
print("未知工具 ->", json.dumps(unknown["error"], ensure_ascii=False))
client.proc.stdin.close()
client.proc.wait(timeout=5)
```

运行 `python mcp_client.py`，输出如下。

```text
initialize -> {"protocolVersion": "2025-06-18", "capabilities": {"tools": {"listChanged": false}}, "serverInfo": {"name": "minimal-adder", "version": "0.1.0"}, "instructions": "使用 add 计算两数之和。"}
tools/list -> {"tools": [{"name": "add", "title": "两数相加", "description": "返回两个数字 a 与 b 的和，结果绝对值不得超过 1000。", "inputSchema": {"type": "object", "properties": {"a": {"type": "number"}, "b": {"type": "number"}}, "required": ["a", "b"], "additionalProperties": false}, "annotations": {"readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false}}]}
tools/call -> {"content": [{"type": "text", "text": "{\"sum\": 42}"}], "structuredContent": {"sum": 42}, "isError": false}
超上限 -> {"content": [{"type": "text", "text": "结果 1100 超出上限 1000"}], "isError": true}
坏参数 -> {"code": -32602, "message": "参数 a 必须是数字"}
未知工具 -> {"code": -32602, "message": "未知工具：sub"}
```

对应的线上消息序列为七条。第 3 条是通知，没有响应；第 4 条与第 6 条是客户端在收到上一条响应后继续发出的请求。

```text
1  C→S  {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}
2  S→C  {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18",...}}
3  C→S  {"jsonrpc":"2.0","method":"notifications/initialized"}
4  C→S  {"jsonrpc":"2.0","id":2,"method":"tools/list"}
5  S→C  {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
6  C→S  {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add",...}}
7  S→C  {"jsonrpc":"2.0","id":3,"result":{"content":[...],"isError":false}}
```

`request` 中的循环是必要的：连接上可能先到服务端发起的请求或日志通知，按 `id` 过滤可以跳过它们。用固定 `sleep` 等待响应不可靠，因为延迟随负载变化；正确做法是阻塞读取直到匹配的 `id` 出现，并在需要超时时改用 `select` 或独立线程计时，不能靠猜测延迟。`client.proc.stdin.close()` 触发 Server 的 EOF 分支，`wait(timeout=5)` 保证不留下孤儿进程；去掉这两行，子进程会一直等待输入。

错误示例印证第 5 节的两个通道：坏参数与未知工具都返回 `error` 且码为 `-32602`，因为参数不符合 `inputSchema`、工具名不存在属于协议层错误，模型无法通过重试修正；超上限返回 `result` 且 `isError` 为真，因为工具已经执行并判定结果违反业务规则，模型可以据此调整参数。前者应由 Host 修正调用或记录集成缺陷，后者应原样回填给模型。

## 易错点

> [!warning] 以下六条均可在运行结果或日志中直接检验。
> 1. 把日志或调试输出写入标准输出。`print` 一行就会在 JSON 流中插入非 JSON 文本，客户端在无关字节处报解析错误；日志必须走标准错误，并在每条响应后刷新标准输出。
> 2. 未初始化即调用，或重复初始化。握手前发送 `tools/list` 会得到 `-32600` 或被直接断开；客户端在 `initialize` 响应到达前发送 `initialized` 通知，会让服务端在版本未定的情况下进入就绪状态。
> 3. 模式类型与实际值不一致。`"type": "integer"` 在 Python 中会接受 `True`，因为布尔值是整数的子类；`"type": "number"` 不接受字符串 `"19"`，但很多客户端会把表单输入当字符串发送。校验必须在 Host 与 Server 两侧都做，且先排除布尔值。
> 4. 超时后既不取消也不释放映射。Host 超时后直接丢弃请求，Server 继续执行并最终写回响应，该响应的 `id` 已不在映射表中，可能被误配给新请求；正确做法是发送 `notifications/cancelled`、保留 `id` 直到收到响应或会话结束、并标记迟到响应。
> 5. 忽略 stdio 的缓冲与编码。父进程写入后不刷新，Server 永远收不到请求；Server 不刷新，Client 阻塞在读取；Windows 上不把三个流设为 UTF-8，中文内容会以本地代码页编码，父进程按 UTF-8 解码时报 `UnicodeDecodeError`。
> 6. 把能力声明或 `annotations` 当作保证。声明 `tools` 不代表每次调用成功；`readOnlyHint` 只是提示，恶意 Server 可以标注只读却执行写操作。Host 必须独立判断风险，不能把提示字段作为权限依据。

## 关联笔记

- 前置 [[AI-Agent与工具调用]]：工具的三元组、调用意图与结果回填是该篇的主体，本篇把这些对象提升为跨进程协议。
- 前置 [[结构化输出]]：`inputSchema` 与 `outputSchema` 的语义、必填性与 `additionalProperties` 规则来自 JSON Schema，该篇第 2 节给出了关键字的完整对照。
- 后续 [[Harness与Loop工程]]：Host 把 Client 当作工具执行层的一个后端，循环、预算、重试与轨迹在该篇展开；本篇的错误分层对应其错误分类表。
- 后续 [[Agent工作流与编排]]：多 Server 的路由、信任域划分与审批策略属于编排层，本篇只提供连接与能力模型。
- 对照 [[RAG原理与流程]]：资源是应用推送上下文，检索是系统按查询拉取上下文，两者的注入风险相同而触发时机不同。

## 达标检测

- [ ] 写出 $M$ 个宿主与 $N$ 个提供者的适配器数量对比，并说明协议化减少了哪一部分工作量、没有减少哪一部分。
- [ ] 给出 `initialize` 的请求与响应字段，说明版本协商在客户端不支持服务端版本时的正确行为。
- [ ] 判断下列三种失败分别属于哪一层并给出返回方式：工具名不存在、参数 `a` 为字符串、下游数据库连接超时。
- [ ] 实现一个 stdio Server，提供 `echo` 工具，并验证在握手前发送 `tools/call` 会得到 `-32600`。
- [ ] 写出一次带取消的工具调用时序，说明接收方在收到 `notifications/cancelled` 后是否应发送响应。
- [ ] 列出工具投毒、令牌透传、跨 Server 注入三种风险的触发条件与至少一条缓解措施。
- [ ] 把本篇 `add` 工具的 `inputSchema` 转换为函数调用严格模式可接受的模式，指出需要修改的字段。

## 参考来源

- Model Context Protocol 规范，modelcontextprotocol.io，`2025-06-18` 版 —— 对应第 2 至第 10 节的传输、消息、握手、三类原语、取消与错误码。
- Anthropic, "Introducing the Model Context Protocol", 2024 —— 对应第 1 节的角色划分与第 5 节的工具设计动机。
- JSON-RPC 2.0 Specification，jsonrpc.org —— 对应第 3 节的请求、响应、通知与错误对象规则。
- Claude Desktop 文档 —— 对应第 1 节 Host 的实际形态与第 11 节的用户同意流程。
- MCP Security Best Practices，modelcontextprotocol.io —— 对应第 11 节的混淆代理、令牌透传、会话劫持与本地 Server 风险。
