MCP 协议解剖：tools/list、tools/call 与凭证代理

先算一笔账：3 个各有 OpenAPI 的内部应用，对 6 个团队的 agent，点对点集成是 3×6=18 份，上游 key 散落 6 处。直连 REST 当然跑得通，那 MCP（Model Context Protocol）多解决了什么？发现、调用、鉴权，这三份契约由谁保管。

MCP 把三份契约从每一对点对点集成里收拢到 server 一侧，其中凭证代理（credential brokering）是工程上最值钱的一环：模型从头到尾看不见任何一把钥匙。

一、拓扑与两个动词：host、client、server

MCP 的拓扑一张图讲完（slides L2 p.41-46）：host 是 AI 应用本身，模型与 agent 循环跑在这里；host 内部为每个工具服务各起一个 client，client 与 server 一对一连接。

server 有两种形态：本地 stdio 进程，例如 Filesystem server，读写本机文件；或远程 HTTP 服务，例如 Sentry server，查线上错误面板。一个 host 挂多个 client，agent 就同时够得着本地文件系统与线上观测系统。

先把定位说清（slides L2 p.41-46）：MCP 是另一种 agent 侧接口标准，并非调 REST 的必需品。agent 解析 OpenAPI 文档、直接构造 HTTP 调用完全成立；MCP 提供的是运行时的标准契约。

细读 Model Context Protocol 官方规范（2026-07-28 版）会发现，协议生命周期就靠两个动词撑着。连接建立后，client 先发 tools/list 取回工具清单，每项是名称、描述与 JSON Schema 参数；运行中要动手时，发 tools/call 携带参数、经 MCP transport 拿回结果。发现是运行时的事，不必预先把接口文档塞进提示词。

存量 REST 资产想零改造接入，用 FastMCP.from_openapi：它把一份 OpenAPI 文档的每个路由投影为一个可发现的 MCP tool。投影后出现在 tools/list 返回里的条目，大致长这样：

{
  "name": "get_order",
  "description": "查询单个订单详情",
  "inputSchema": {
    "type": "object",
    "properties": { "order_id": { "type": "string" } },
    "required": ["order_id"]
  }
}

上游一行没改，agent 侧多了一个可发现的工具。

二、四行契约：OpenAPI/HTTP 对照 MCP

slides L2 p.46 用一张四行对照表把两套体系的差异收拢，值得整张抄下来：

前三行是同一件事换了个管法：发现从拉文档变成运行时动词；调用从 HTTP verb 加 path 变成经 transport 的 tools/call；鉴权从「客户端直接向 API 认证」变成「客户端向 MCP 认证、上游认证独立」。第三行是下一节凭证代理的伏笔。

第四行是范围之差：OpenAPI 只描述 HTTP 操作，MCP 除 tools 外还支持 resources、prompts 等扩展原语，接口标准从怎么调接口，扩到给 agent 提供哪些上下文原语。

而两边共享 JSON Schema 词汇，意味着从 OpenAPI 到 MCP 是翻译题，不是重写题；from_openapi 的投影之所以能机械完成，根子在这里。

三、凭证代理：两把钥匙各管一段

先看没有 MCP 时的风险（slides L2 p.40）：coding agent 天然有 shell 权限，上游 API key 只要出现在它的环境变量里，就可能被读取、被滥用；你没法靠提示词保证模型永远听话。

MCP 的解法是凭证分离：UPSTREAM_API_KEY 只存在 MCP server 侧，用来调上游 API；MCP_API_KEY 保护 MCP 端点本身，客户端拿它向 MCP 认证。模型坐在 host 里，两把钥匙都看不见，它只接触工具清单与调用结果。

这就是凭证代理：钥匙的保管与使用被代理到 server，信任边界从每个 agent 环境收缩到 server 一侧。

落到代码上是两段职责分明的读取：

# MCP server 侧：两把钥匙各管一段
import os

upstream_key = os.environ["UPSTREAM_API_KEY"]  # 只用于调上游 API，绝不发往 client
mcp_key = os.environ["MCP_API_KEY"]            # 只用于校验来访 client（客户端向 MCP 认证）

四、从 18 份集成到 N+M：MCP 不保证什么

凭证集中的收益，要到规模上才看得全。slides 的算例：3 个各有 OpenAPI 的内部应用，对 6 个团队的 agent 应用，点对点集成是 3×6=18 份，且每份都要把上游 key 配到对应 agent 的环境里，钥匙散落 6 处。

MCP 化之后是 N+M：3 个 server 加每团队 1 个 client，集成份数从乘法变加法，凭证全部集中到 server 侧。

但边界要画清：MCP 保证的是发现、调用、鉴权的契约，不保证模型选对工具，也不保证参数语义正确；那是评测里 Selection 与 Arguments 两层的事。工具本身设计得好不好，仍在人手里。

Anthropic 工程博客 Writing effective tools for agents 给的四条手感：

• 命名要准；
• 描述要说清何时用；
• 参数尽量少；
• 错误信息要写成模型能据此自我修复的样子。

协议替你省下的只有管道，判断仍归人。

与本讲的连接

本篇下钻的是讲次页「核心概念梳理・接口的形状」板块的工程侧。伴读笔记把接口摆成细粒度函数与通用程序接口的光谱，本篇补的是这层契约与钥匙由谁保管。

ReAct 轨迹篇里随请求写死的 tools 清单，在这里换成 tools/list 的运行时发现；schema 三部曲里各家共享的 JSON Schema 词汇，则让两个世界直接互通。资料卡对应三条延伸线：

• MCP 官方规范：读协议本体。
• Writing effective tools for agents：回到工具设计的人机分工。
• The Agent Network（Latent Space 播客）：把 agent 接入网络摆到生态视角，本篇讲的两个动词，就是入网的最小握手。

两个动词归协议，两把钥匙归 server，模型从头到尾不碰任何一把。