以下工具、schema 与错误码均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。-32700/-32601/-32602 沿用 JSON-RPC 2.0 的错误码约定,但 MCP 消息的具体字段以官方规范为准,‘分层处理’这一条不变。
模型会"说"它要调用工具,协议负责把这句话变成可执行的消息。Function Calling 是模型侧的能力(模型输出结构化的工具调用意图),MCP 是系统侧的协议(这个意图怎么被解析、校验、路由、执行)。两者接起来,工具调用才成立。
MCP 的架构价值在于分层:传输层管通道,消息层校验 JSON-RPC 结构,语义层按注册表查找并执行工具。错误在哪个层产生,就由哪个层返回对应的错误码——这让 Agent 侧能精确区分"消息格式错了"和"工具不存在"。
三层各管什么
| 层 | 职责 | 错误示例 | 错误码 |
|---|---|---|---|
| 传输层 | 通道与连接 | (本实验略过) | — |
| 消息层 | 校验 JSON-RPC 结构 | jsonrpc 不是 2.0、缺 method | -32700 |
| 语义层 | 查表、校验参数、执行 | 工具不存在、参数缺失 | -32601 / -32602 |
消息层管结构。 每一条调用消息必须符合 JSON-RPC 2.0:有 jsonrpc 字段、有 method。结构错了,连"要调什么工具"都读不出来,直接返回协议错误。
语义层管内容。 method 读出来之后,要在注册表里找到这个工具:找不到是"未知工具",找到了但参数不对是"参数无效"。语义层的错误码细分(-32601 工具不存在、-32602 参数无效),让 Agent 侧不用解析消息就能知道是哪一类失败。
分层错误的好处:Agent 侧能分类响应
分层的收益在消费侧。Agent 收到不同错误码,可以做出不同反应:
| 错误码 | 含义 | Agent 侧响应 |
|---|---|---|
| -32700 | 协议错误 | 不是工具问题,是消息问题;检查调用构造 |
| -32601 | 工具不存在 | 不该再调用;注册表有误 |
| -32602 | 参数无效 | 重新构造参数(见 5.1 校验) |
如果错误不分层,Agent 侧只能用错误消息字符串做匹配,脆且容易误判。错误码让"这是什么问题、该怎么处理"结构化。
最小实验:分层 dispatch
实验实现最小的 JSON-RPC 解析、工具注册表与分层 dispatch。
# file: agp_lab/mcp_protocol.py | write
# tier: 3
# verify: python3 -m unittest tests.test_mcp_protocol
"""Function Calling 与 MCP:协议分层、消息校验与工具注册。
MCP 把工具调用分层处理:传输层负责通道,消息层校验
JSON-RPC 结构与字段,语义层按注册表查找并执行工具。
错误在哪个层产生,就由哪个层返回对应的错误码。
本模块实现最小的 JSON-RPC 解析、工具注册表与分层 dispatch,
演示合法调用、未知工具与协议错误三种路径。
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Callable
class ProtocolError(Exception):
pass
class UnknownToolError(Exception):
pass
@dataclass(frozen=True)
class McpMessage:
id: int | None
method: str
params: dict[str, Any]
def parse_message(raw: dict[str, Any]) -> McpMessage:
"""消息层:校验 JSON-RPC 2.0 的字段。"""
if raw.get("jsonrpc") != "2.0":
raise ProtocolError("jsonrpc 必须为 2.0")
if "method" not in raw:
raise ProtocolError("缺 method")
return McpMessage(raw.get("id"), raw["method"], raw.get("params", {}))
def _validate(params: dict[str, Any], schema: dict[str, Any]) -> list[str]:
errors: list[str] = []
for required in schema.get("required", []):
if required not in params:
errors.append(f"missing required '{required}'")
return errors
class ToolRegistry:
"""语义层:按名称查找工具并执行。"""
def __init__(self) -> None:
self.tools: dict[str, tuple[Callable[[dict[str, Any]], Any], dict[str, Any]]] = {}
def register(self, name: str, handler: Callable[[dict[str, Any]], Any], schema: dict[str, Any]) -> None:
self.tools[name] = (handler, schema)
def call(self, name: str, params: dict[str, Any]) -> Any:
if name not in self.tools:
raise UnknownToolError(f"unknown tool: {name}")
handler, schema = self.tools[name]
errors = _validate(params, schema)
if errors:
raise ValueError(f"invalid params: {errors}")
return handler(params)
def dispatch(raw: dict[str, Any], registry: ToolRegistry) -> dict[str, Any]:
"""分层 dispatch:消息层 → 语义层,错误就近返回。"""
try:
message = parse_message(raw)
except ProtocolError as error:
return {"jsonrpc": "2.0", "error": {"code": -32700, "message": str(error)}}
try:
result = registry.call(message.method, message.params)
return {"jsonrpc": "2.0", "id": message.id, "result": result}
except UnknownToolError as error:
return {"jsonrpc": "2.0", "id": message.id, "error": {"code": -32601, "message": str(error)}}
except ValueError as error:
return {"jsonrpc": "2.0", "id": message.id, "error": {"code": -32602, "message": str(error)}}
def demo() -> dict[str, Any]:
registry = ToolRegistry()
registry.register("read_file", lambda p: f"content of {p['file']}", {"required": ["file"]})
return {
"ok": dispatch({"jsonrpc": "2.0", "id": 1, "method": "read_file", "params": {"file": "a.txt"}}, registry),
"unknown_tool": dispatch({"jsonrpc": "2.0", "id": 2, "method": "rm_rf", "params": {}}, registry),
"protocol_error": dispatch({"id": 3, "method": "read_file"}, registry),
"bad_params": dispatch({"jsonrpc": "2.0", "id": 4, "method": "read_file", "params": {}}, registry),
}
if __name__ == "__main__":
for key, value in demo().items():
print(f"{key}: {value}")
运行:
cd private/labs/agp-lab
python3 -m agp_lab.mcp_protocol
输出:
ok: {'jsonrpc': '2.0', 'id': 1, 'result': 'content of a.txt'}
unknown_tool: {'jsonrpc': '2.0', 'id': 2, 'error': {'code': -32601, 'message': 'unknown tool: rm_rf'}}
protocol_error: {'jsonrpc': '2.0', 'error': {'code': -32700, 'message': 'jsonrpc 必须为 2.0'}}
bad_params: {'jsonrpc': '2.0', 'id': 4, 'error': {'code': -32602, 'message': 'invalid params: ["missing required \'file\'"]'}}
四条路径覆盖合法与三类失败:
- ok:合法调用 read_file(file=a.txt),返回 result。id 原样回显(1)。
- unknown_tool:调用没注册的 rm_rf,语义层返回 -32601。Agent 侧据此知道"这个工具不存在",不该再试。
- protocol_error:消息没有 jsonrpc 字段,消息层在解析阶段就返回 -32700。注意这条响应没有 id——因为结构都错了,连 id 都没法信任。
- bad_params:read_file 缺必填 file,-32602。注意它与 -32601 是不同的错误码:工具存在、参数无效。
两个值得点破的细节:
- protocol_error 没有 id。 消息层失败发生在拿到 id 之前,响应里就没有 id。这是 JSON-RPC 的语义:id 无效时无法回显,只能返回错误对象。
- 错误码和错误层一一对应。 -32700 只在消息层产生,-32601/-32602 只在语义层产生。这个对应关系就是"分层"的可观测保证:看到错误码,就知道故障在哪个层。
MCP 分层的另一层意义是可插拔。传输层、消息层、语义层解耦之后,替换任何一层都不影响其他层:把 stdio 传输换成 HTTP,把本地注册表换成远程注册中心,Agent 侧的调用方式不变。这正是一个协议应有的结构——它让协议本身演进,而不让使用方跟着改。
| 替换场景 | 替换哪层 | Agent 侧影响 |
|---|---|---|
| stdio → HTTP | 传输层 | 无 |
| 本地 → 远程注册 | 语义层 | 无(接口不变) |
| JSON-RPC → 其他 | 消息层 | 适配器 |
分层的代价也有:每一层都是故障点。传输层断了、消息层解析失败、语义层查表超时,三层各自要监控。错误码的设计,让监控可以直接定位到层——看到 -32700 就知道是消息层,看到 -32601 就知道是语义层。这是"分层 + 错误码"组合的可观测价值。
MCP 的生命周期管理是把它用进生产的前提。工具要能注册、下线、灰度、回滚,而不仅仅是"能调用"。一个典型流程:新工具先在注册表里标实验态,只对部分 Agent 可见;验证稳定后转正式;废弃工具先标 deprecated 再下线,给存量会话迁移窗口。注册表不是静态清单,是带状态的工具生命周期系统。
| 生命周期 | 状态 | 调用方可见 |
|---|---|---|
| 开发中 | experimental | 部分 |
| 已验证 | active | 全部 |
| 废弃中 | deprecated | 全部(提示迁移) |
| 已下线 | removed | 不可见 |
安全维度上,MCP 还有一层信任边界:工具注册源可信吗?Agent 调工具前,运行时要不要校验工具的签名或来源?对任意来源的 MCP 服务器不加校验,等于给 Agent 开放任意代码执行。MCP 的接入策略要和 4.3 的能力边界配合——谁有权限接入 MCP 服务器、能声明哪些能力,都要有约束。
MCP 的传输选择要匹配部署形态。stdio 传输适合"Agent 与工具同进程或同机",HTTP 适合分布式部署(工具服务器独立运行、Agent 通过网络访问)。传输层选择影响运维:stdio 的进程由 Agent 拉起、生命周期跟随 Agent;HTTP 的工具服务独立部署、要单独监控与扩容。
| 传输 | 部署形态 | 运维特点 |
|---|---|---|
| stdio | 同进程/同机 | 进程随 Agent 生灭 |
| HTTP | 独立服务 | 单独监控、扩容 |
| SSE | 长连接流式 | 连接管理复杂 |
错误码的语义要在 MCP 层与工具层对齐。 MCP 层的 -32601 表示"方法不存在",工具层的错误要复用或扩展现有语义,而不是另起一套。错误码分层(MCP 层协议错误、工具层业务错误)各司其职,Agent 侧才能按层处理——协议错误修调用,业务错误改参数。
MCP 的注册表设计决定 Agent 能发现什么工具。按能力索引(如"能做 web_search")、按领域分组、带健康状态——Agent 查询"我要做 X,有什么工具",注册表返回可用且健康的工具。注册表不只是存工具定义,还是 Agent 的"工具路由"。
| 注册表能力 | 作用 | 缺失后果 |
|---|---|---|
| 按能力索引 | 语义查询 | 只能按名找 |
| 健康状态 | 剔除故障工具 | 调到坏工具 |
| 版本信息 | 兼容判断 | 调用旧版本 |
| 权重/优先级 | 排序选择 | 随机选工具 |
架构判据
工具调用协议是否合格,用五条判据检查:
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 分层清晰 | 消息层/语义层职责分明 | 解析与执行混在一起 |
| 错误码细分 | 协议/工具/参数错误可区分 | 所有错误一个码 |
| 注册表单源 | 工具按名称查注册表 | 工具散落、无注册 |
| 参数校验 | 调用前校验 schema | 参数错进到执行层 |
| 错误可分类响应 | Agent 侧按错误码响应 | 靠字符串匹配错误 |
判据第三条"注册表单源"是 MCP 的核心:工具按名称注册、按名称查找,Agent 侧只需要知道名称和 schema。判据第四条呼应 5.1:参数校验在调用前拦截,别让坏参数进到工具。
小结
- Function Calling 是模型侧能力,MCP 是系统侧协议;两者接起来工具调用才成立。
- MCP 分层处理:传输层、消息层、语义层;错误在哪个层产生就由哪个层返回错误码。
- 错误码细分让 Agent 侧能分类响应:协议错误、工具不存在、参数无效互不相同。
- 分层是可观测保证:看到错误码就知道故障在哪个层。
阅读导航:上一节:5.3 补偿、回滚与 Saga · 下一节:6.2 A2A:Agent 间协作协议 。
常见错误与边界
- 解析与执行混在一起。 不校验结构就去找工具,协议错误会被误报成工具不存在。
- 所有错误一个码。 Agent 侧无法区分"消息坏了"与"工具没了";要按层细分错误码。
- 工具不注册。 工具散落在代码里,Agent 侧无从发现;要按名称查注册表。
- 参数错进执行层。 校验在调用前拦截;坏参数进去就是副作用已发生(见 1.1)。
- protocol_error 也回显 id。 消息层失败时 id 不可信,不能回显;要返回纯错误对象。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。