MCP 协议:让模型安全接入业务系统
本篇要点:读完能判断一个业务系统该用工具、资源还是提示暴露给模型,能把自己的 MCP Server 配上 Origin 校验、stderr 日志和可纠正的错误,再挂到公网。前置要求:《工具调用:Function Calling 设计》已经写过 Function Calling 的工具 schema,知道模型是按 JSON Schema 生成参数的。
为什么需要它
2026 年 3 月,一个订单运维智能体要接三个系统:订单库、库存、工单。第一版是三个私有适配器,每个系统一份工具定义、一份鉴权代码、一份错误映射。三周后换模型供应商,三份全要重写,因为各家的工具调用格式不一样。
MCP(Model Context Protocol,模型上下文协议)把这层抽出来:业务系统按协议写一次 Server,任何支持 MCP 的 Host 都能接。N 个应用乘 M 个系统的适配量,塌成 N 加 M。
代价出现在挂公网之后:难点不在协议设计,而在鉴权、密钥、负载均衡、SDK 大版本改名。截至 2026 年 11 月,规范当前版本是 2026-07-28,它替换 2025-11-25,再往前是 2025-06-18、2025-03-26、2024-11-05,每版变更见 MCP 规范变更记录。SDK 侧 Python 在 2.x 线、TypeScript 在 1.x 线,两边不同步;小版本号看 官方 SDK 仓库 的 release 页,两三个月跳一次,不适合写死在教材里。
核心概念
概念一:Host、Client、Server 是三个角色
Host 是那个 AI 应用——Claude Desktop、Claude Code、自研的 Agent 运行时都算。Host 为每个要连的 Server 建一个 Client,Client 维护一条独立连接、协商能力、转发消息。Server 是被接入的一侧,对外声明自己有哪些工具、资源、提示。三者的关系如图 4-1。
图 4-1 Host 为每个 Server 建一个 Client,两种传输只是管道不同
图 4-1 里的分工可以压成一句话:Host 决定「允许用哪些 Server」,Client 管「这条连接怎么说话」,Server 管「我能提供什么」。
反例是把业务后端叫成 Host。业务后端是被调的一方,它是 Server;Host 是握着模型和对话的那一端。这一层搞错,鉴权会做在错误的位置——Host 该决定给这个用户挂哪些 Server,Server 只该判断这个 token 有没有对应的 scope(授权范围)。
本地 stdio Server 通常只服务一个 Client(Client 拉起子进程就有了连接);远程 Streamable HTTP Server 服务很多客户端,是本篇的重点。
概念二:工具、资源、提示,差别在「谁决定用不用」
Server 侧有三个原语(primitive),官方给了对照表,但那张表看不出决策权,按「谁决定用不用」重排如表 4-1。
| 原语 | 是什么 | 谁决定用不用 | 典型用法 |
|---|---|---|---|
| Tools 工具 | 有副作用的动作,输入输出用 JSON Schema 描述 | 模型自己判断 | 下工单、发通知、改配置 |
| Resources 资源 | 只读数据,按 URI 寻址 | Host 决定塞不塞进上下文 | 知识库文档、表结构、接口说明 |
| Prompts 提示 | 预置指令模板 | 用户主动选 | 「按排障流程检查这个告警」 |
表 4-1 三个原语的判断依据是决策权归谁
判断办法很短:需要模型自己决定「现在要不要做这件事」的是工具;需要在对话开始前就把背景铺好的是资源;需要人点一下才触发的固定流程是提示。
两个反例都真实发生过。把「查日志」做成资源,模型看不见也不主动拉,回答就永远停在「不知道日志在哪」,改成工具立刻正常。反过来,把一份 30MB 的运维手册做成工具,模型为了看一眼目录结构就调一次,白烧 token;手册是典型的资源,工具只留「按文章号取一段」。
概念三:stdio 与 Streamable HTTP 的坑不在同一处
stdio 的协议部分很简单:Client 拉起子进程,换行分隔的 JSON-RPC 走标准流。坑在日志。只要有一行调试信息进了 stdout,它就会被当成协议消息解析,客户端报一句看不懂的解析错误。所有日志必须走 stderr,而最常见的污染源是第三方库在初始化里打了一行版本号。
Streamable HTTP 的硬要求密得多,漏一条会被某些客户端直接拒:
- 单个 endpoint 路径(例如
https://example.com/mcp)接 POST,每个 JSON-RPC 消息都是一次独立 POST; Accept必须同时列application/json和text/event-stream,客户端两种都要支持;- 服务端返回
application/json或一条 SSE 流(SSE,Server-Sent Events,服务端推送事件),流里只允许带与本次请求相关的通知,最终响应结束时关闭流。
最容易被忽略的是 Origin。服务端必须校验 Origin 头以防 DNS 重绑定(DNS rebinding),不合法回 403;本地运行时只绑 127.0.0.1,不要绑 0.0.0.0。绑了 0.0.0.0 又不校验 Origin,等于任何网页都能让访客的浏览器去打那个端口,这是这类服务的默认失败模式,不是理论风险。
还有一条影响网关改造:这一版规范要求 POST 带上 Mcp-Method、Mcp-Name 两个标准头,中间层不用解包 body 就能路由和审计;方法不存在要回 404 加 JSON-RPC 的 -32601。在网关上按 Mcp-Method 计数限流,比按路径猜准得多。
概念四:会话删掉之后,状态要自己显式传
2026-07-28 这版改动大到不像小版本。协议级会话没了,Mcp-Session-Id 头从 Streamable HTTP 里删掉;initialize 与 notifications/initialized 握手也没了,每个请求自己在 _meta 里带 io.modelcontextprotocol/protocolVersion、clientCapabilities、clientInfo;新增一个必须实现的 server/discover,返回支持哪些协议版本、有哪些能力、自己是谁。
方向等于把无状态 REST 又走了一遍。收益很直接:以前一个请求必须落回同一台机器,扩容要配粘性会话,滚动发布时那批活会话全断;现在任意副本都能接。
但这句话要读完:无状态只对 2026 时代的客户端成立。2025 时代的客户端仍然开会话,仍然需要旧的粘性配置;SDK 2.x 用同一份 streamable_http_app() 同时服务两代,兼容成本从运维挪进了库。两代请求在链路里的形状如图 4-2。
图 4-2 两代客户端的请求形状,右侧的 InputRequiredResult 是多轮往返
图 4-2 右边那条分支叫多轮往返(MRTR,Multi Round-Trip Request)。工具需要用户补信息时,服务端不再反向发请求,而是返回一个 InputRequiredResult,客户端带着答案重试原调用。
重试如果落到另一台副本,请求里那段封存的 request_state 得能被那台机器解开,而它的默认密钥是按进程随机生成的。多副本部署必须显式传 RequestStateSecurity(keys=[...]),把所有副本的密钥对齐。这个坑单机测不出来,上线第二天开始偶发失败,报错还完全不指向密钥。
概念五:鉴权搬 OAuth,错误分两层
规范的授权文章基本是把 OAuth 2.1 那套搬过来:授权服务器发现、客户端注册、resource 参数指向 Server 的规范 URI、scope 选择、token 必须放 Authorization: Bearer、scope 不足走 step-up 增量授权。
不建议给 MCP Server 自研 token 方案。用「内部 API Key 放自定义头」跑两周就会撞上三件事:Host 侧没法做增量授权,用户想多给一个权限得重配整个连接;token 轮换要手动改客户端配置;审计里分不清是人还是某个 Agent 发起的。换成 OAuth 之后,scope 粒度、刷新、撤销都是标准动作,客户端也认。
远程 Server 的 tools/list 允许按请求带的授权变化:只返回调用者 scope 覆盖得到的工具。同一个 Server,普通用户看到只读工具,运维看到写工具。代价是工具列表不稳定,客户端缓存要按凭据维度切分;规范为此要求服务端按确定性顺序返回工具,一是方便缓存,二是提高提示缓存(prompt caching)命中率——工具定义进了模型上下文之后,顺序一变缓存就废。
错误分两类,这个分法比多数 RPC 框架实用。协议级错误用 JSON-RPC 的 error 返回:工具不存在、请求结构不合法、服务端内部错误。这类错误模型基本修不了,问题在调用方代码或框架。执行级错误用 result.isError: true 返回,里面是给模型看的自然语言,规范的说法是「提供可操作反馈,让模型能自己纠正后重试」,客户端 SHOULD 把这类错误交给模型。
动手实践
步骤 1:用 2.x SDK 写一个 Server
先记住这次改名的力度:FastMCP 改名 MCPServer,旧路径不是废弃而是直接删除。import mcp.server.fastmcp 会得到一个刻意写好的 ModuleNotFoundError,提示你「这是 mcp 2.x,FastMCP 已改名 MCPServer,或者 pin 到 mcp<2」。装饰器写法几乎没变,@mcp.tool()、@mcp.resource()、@mcp.prompt() 都还在,schema 仍从类型标注生成;变的是周边:ctx.fastmcp 变 ctx.mcp_server,get_context() 改成声明 ctx: Context 参数,FastMCPError 变 MCPServerError,McpError 变 MCPError,传输配置挪进了 run()。
from mcp.server import MCPServer # 2.x:FastMCP 已改名,旧路径被删除
from mcp.server.exceptions import ToolError # 异常模块路径以 2.x 当期文档为准
mcp = MCPServer("订单运维")
@mcp.tool()
def get_order_status(order_no: str) -> dict:
"""按订单号查状态。order_no 形如 DD 加 11 位数字,查不到返回 not_found。"""
if not (order_no.startswith("DD") and len(order_no) == 13):
# 业务失败抛 ToolError,框架会包成 result.isError 交给模型
raise ToolError("order_no 格式错误:应为 DD 加 11 位数字")
return {"order_no": order_no, "status": "shipped"}
@mcp.resource("order://schema")
def order_schema() -> str:
"""订单主表结构,由 Host 决定是否放进上下文。"""
return "orders(id, order_no, status, created_at)"
if __name__ == "__main__":
# 多副本部署时必须显式传 RequestStateSecurity(keys=[...]),
# 让所有副本共用同一把 request_state 密钥;参数名以 2.x 当期文档为准
mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)运行结果(Inspector 里发 tools/list,只列关键字段):
{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"get_order_status",
"description":"按订单号查状态。order_no 形如 DD 加 11 位数字,查不到返回 not_found。",
"inputSchema":{"type":"object","properties":{"order_no":{"type":"string"}},
"required":["order_no"]}}]}}描述里那句格式说明会原样进模型上下文,它决定了模型会不会在第一次调用就传对参数,比代码注释重要。
另外提醒一处 v1 与 v2 的实质差别:v1 的低层 Server 会在 handler 之前用 jsonschema 校验参数,v2 里 schema 只是对外声明,不再校验。v1 代码里那句「反正 SDK 校验过了,arguments["query"] 直接用」在 v2 是空指针,迁移时必须自己补校验。
步骤 2:上线前先过三个检查
# 1. 不带 Origin:必须被拒
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Mcp-Method: tools/list' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# 2. 带合法 Origin:应当通过
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Mcp-Method: tools/list' -H 'Origin: http://127.0.0.1:8000' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# 3. 确认 stdout 干净(协议专用),日志只在 stderr
python server.py 1>/tmp/mcp.stdout 2>/tmp/mcp.stderr &
sleep 2 && wc -c /tmp/mcp.stdout运行结果:
403
200
0 /tmp/mcp.stdout三条里最容易漏的是第三条。wc -c 打出 0 才说明 stdout 没有被日志污染,否则第一次接客户端就会报解析错误,而且报错位置指向客户端。
步骤 3:把业务失败做成可纠正的错误
import httpx
def call(method: str, params: dict) -> dict:
r = httpx.post("http://127.0.0.1:8000/mcp",
headers={"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"Origin": "http://127.0.0.1:8000",
"Mcp-Method": method},
json={"jsonrpc": "2.0", "id": 1, "method": method, "params": params})
return r.json()
# 协议级:方法不存在,模型重试也没用
print(call("tools/nope", {})["error"]["code"])
# 执行级:参数不合法,但模型能读懂并自己改
res = call("tools/call", {"name": "get_order_status",
"arguments": {"order_no": "12345"}})["result"]
print(res["isError"], res["content"][0]["text"])预期输出:
-32601
True order_no 格式错误:应为 DD 加 11 位数字第二行就是执行级错误的写法:说清哪错了、合法值长什么样,模型下一轮通常能自己改对。最容易犯的错,是把「参数校验失败」写成裸的 raise ValueError 让它冒成协议错误,模型收不到可纠正的信息,只会一遍遍重发同样的参数。凡是业务上能描述清楚的失败,都用 ToolError 抛、走 isError: true;只有调用方代码写错这类模型改不了的问题,才交给协议层 error。
常见误解
误解一:MCP 是又一个 RPC 框架,重点在协议设计。协议本身的构成很薄,难的是周边:Origin 与绑定地址、跨副本的密钥对齐、按 scope 变化的工具列表、网关上的计数限流。把时间全投在 schema 设计上,上线第一周还是会被安全和运维问题按住。
误解二:SDK 2.x 只是改名,装饰器没动就能平滑升级。装饰器确实没动,但参数校验被移走了,ctx 的拿法变了,异常基类全改名,传输配置换了位置。升级前需要 grep 三样东西:fastmcp、get_context、arguments[。
误解三:工具列表是稳定的,客户端可以一直缓存。远程 Server 按 scope 返回不同工具集,同一个 URL 对不同凭据就是不同视图。规范要求服务端按确定性顺序返回,是因为顺序变了提示缓存会失效,不是因为列表本身不变。
小结
- Host、Client、Server 是三个角色。Host 决定挂哪些 Server,Server 只判断 token 有没有对应 scope。
- 三个原语按决策权分:模型决定用工具,Host 决定塞不塞资源,用户决定触发哪个提示。
- stdio 的死穴是 stdout 日志;Streamable HTTP 的死穴是 Origin 校验与
127.0.0.1绑定。 - 会话删掉之后,跨调用状态要显式传;多副本必须对齐
request_state密钥。 - 业务上能说清的失败走
result.isError,说不清的才走协议error。
相关主题
工具打通了业务系统,但模型对业务知识仍然一无所知:它能查订单状态,却不知道出差住宿标准是多少、哪份制度适用于哪个城市。《RAG 检索增强:从文档到可用知识库》讲 RAG 检索增强——怎么把一堆文档变成能按问题取回几条的候选池,以及召回率上不去时怎么判断坏在哪一层。