MCP 的 demo 很容易跑通,生产级 Server 却很难做对:协议只规定了"怎么说话",没规定并发、鉴权、超时、可观测性——而这些恰恰是 Agent 调用工具时最先崩的地方。
一、问题定位
MCP 的生产故障几乎都不在协议握手,而在握手之后。最常见的模式是:Server 用 stdio 本地跑得好好的,一上 HTTP 就出现会话串线——多个 Client 共享同一个无状态处理函数,工具执行到一半被另一个请求的 notifications/cancelled 打断;或者工具没有超时,一个慢 SQL 把连接池占满,整个 Agent 会话雪崩。
第二类故障是权限与资源治理缺失。MCP 的 Tool 是"有副作用的操作",默认语义是"能调就调"。如果没有在 Server 侧做能力白名单、参数校验、租户隔离与审计,Agent 的一次幻觉调用就可能变成越权读文件、删库或把内部数据发往外部端点。协议把安全责任留给了实现者,这是设计上的刻意,也是工程上的大坑。
第三类是可观测性缺失。工具调用链一旦跨进程,日志、指标、追踪就要重建:哪个 Client 在什么会话里调了哪个工具、耗时多少、失败在哪一步、token 消耗多少。没有这层数据,生产问题只能靠猜,容量规划也无从谈起。
1.1 为什么现在更值得讨论
- Streamable HTTP 成为默认传输:旧的 SSE 加 HTTP 双端点模式被更简洁的流式 HTTP 取代,会话恢复与
Mcp-Session-Id成为生产必选项。 - 工具调用进入长任务时代:单次数十分钟的分析、批量数据迁移、代码生成后自动执行,要求 Server 支持取消、进度通知与幂等重试。
- 多租户与合规压力:企业内 Agent 平台必须按租户隔离工具与数据,MCP Server 从"工具提供者"升级为"受治理的能力网关"。
二、按要点拆解:MCP 协议与生产 Server 架构
2.1 协议交互与生命周期
一次完整交互从 initialize 开始:Client 发送协议版本与能力声明,Server 回 result(含 serverInfo、capabilities),随后 Client 发 notifications/initialized 完成握手。此后 Client 可发 tools/list 拉取工具 schema,模型据此决定调用;真正执行走 tools/call,Server 返回 content(text、image、resource)。长任务期间 Server 可通过 notifications/progress 回报进度,Client 可发 notifications/cancelled 中断。
- 能力协商:
capabilities里声明tools、resources、prompts及其listChanged,Server 只能暴露声明过的原语,Client 不应假设未声明的接口可用。 - 请求关联:每个 JSON-RPC 请求带
id,响应必须原样回传;通知无id,Server 不得对通知回响应,否则协议直接判错。 - 错误语义:工具执行失败应返回 JSON-RPC
error(含 code 与 message),而不是把错误塞进content让模型自行解读;isError字段则用于"业务性失败但仍可继续推理"的场景。
2.2 传输层与会话管理
MCP 定义了 stdio 与 Streamable HTTP 两类主要传输。stdio 适合本地进程与 CLI,一行一条 JSON-RPC,实现简单但无法跨网络;Streamable HTTP 用单一端点(通常 POST /mcp)承载请求与响应,服务端到客户端的推送走 SSE 流,可选 GET /mcp 做服务器主动通知。
- 会话 ID:Server 在
initialize响应里返回Mcp-Session-Id,后续请求必须携带;水平扩展时必须把会话粘到同一实例,或用 Redis 等共享存储保存会话状态。 - 断线恢复:SSE 流支持
Last-Event-ID,Client 重连后 Server 应能重放断点之后的事件;对长任务尤其关键,否则一次网络抖动就丢进度。 - 无状态与有状态:优先做无状态 Server(会话信息放 Client 或外部存储),实例可随时扩缩容;若必须持有状态,则明确会话亲和与优雅下线策略。
2.3 并发、鉴权与可观测性
- 并发上限与隔离:用信号量限制单实例并发工具调用数,按工具类型分池(CPU 密集、I/O 密集、外部 API),避免一个慢工具拖垮全部能力。
- 超时与取消:
tools/call必须带服务端超时,收到notifications/cancelled后要真正中断底层任务(关闭连接、取消子进程、回滚事务),并返回可重试语义。 - 鉴权与审计:HTTP 传输强制 Bearer 或 OAuth2,Server 校验 token 并映射到租户;工具白名单按角色下发,参数走 JSON Schema 校验,所有调用写审计日志(谁、何时、哪个工具、入参摘要、结果、耗时)。
- 可观测性三件套:指标(QPS、P95/P99、错误率、并发占用)、追踪(一次
tools/call一个 span,串起上游会话 ID)、日志(结构化 JSON,含 session_id 与 tool_name,敏感字段脱敏)。
三、最小可运行实现
思路:用 Python 标准库实现一个最小 Streamable HTTP Server,把 initialize、tools/list、tools/call 与并发限制串起来,作为生产 Server 的骨架。
# mcp_server.py —— 最小 Streamable HTTP MCP Server(Python 3.11+)
import json, time, uuid, threading
from http.server import ThreadingHTTPServer, BaseHTTPRequestHandler
TOOLS = [{
"name": "echo",
"description": "回显输入,演示 tools/call",
"inputSchema": {"type": "object", "properties": {"text": {"type": "string"}},
"required": ["text"]},
}]
_sem = threading.Semaphore(8) # 并发上限:保护下游资源
def rpc(req):
method, rid = req.get("method"), req.get("id")
if method == "initialize":
return {"jsonrpc": "2.0", "id": rid, "result": {
"protocolVersion": "2025-06-18",
"serverInfo": {"name": "demo", "version": "1.0"},
"capabilities": {"tools": {"listChanged": False}},
}}
if method == "notifications/initialized":
return None # 通知:不回响应
if method == "tools/list":
return {"jsonrpc": "2.0", "id": rid, "result": {"tools": TOOLS}}
if method == "tools/call":
if rid is None:
return None
name = req["params"]["name"]
if name not in {t["name"] for t in TOOLS}:
return {"jsonrpc": "2.0", "id": rid,
"error": {"code": -32602, "message": "unknown tool"}}
if not _sem.acquire(timeout=5): # 超时即失败,避免挂死
return {"jsonrpc": "2.0", "id": rid,
"error": {"code": -32001, "message": "server busy"}}
try:
text = req["params"]["arguments"]["text"]
time.sleep(0.01) # 真实工具:DB/HTTP/子进程
return {"jsonrpc": "2.0", "id": rid,
"result": {"content": [{"type": "text", "text": text}]}}
finally:
_sem.release()
return {"jsonrpc": "2.0", "id": rid,
"error": {"code": -32601, "message": "method not found"}}
class H(BaseHTTPRequestHandler):
def do_POST(self):
n = int(self.headers.get("content-length", 0))
req = json.loads(self.rfile.read(n))
self.send_response(200)
self.send_header("content-type", "application/json")
sid = self.headers.get("mcp-session-id") or uuid.uuid4().hex
self.send_header("mcp-session-id", sid)
self.end_headers()
self.wfile.write(json.dumps(rpc(req)).encode())
def log_message(self, *a): pass
ThreadingHTTPServer(("0.0.0.0", 8000), H).serve_forever()
四、常见坑与排查
- 会话串线:检查
Mcp-Session-Id是否在每个请求都带上、负载均衡是否做了会话粘滞;用带会话头的curl单会话复现。 - 通知被当成请求回响应:抓一条原始报文,确认 Server 对
id缺失的 JSON-RPC 消息没有返回 body,否则 Client 会报协议错误。 - 工具挂死:确认
tools/call有服务端超时(不是只靠 Client 超时),并验证notifications/cancelled真的中断了底层任务(连接或子进程)。 - 大 payload 内存暴涨:
content支持 image 与 resource,限制单次返回体积(如 1 MB)与并发返回数,超限截断为摘要加资源引用。 - 鉴权过期:HTTP 传输下确认 token 刷新与 401 重试逻辑;stdio 场景也要防本地提权(限制可执行路径、只读挂载)。
- 日志泄露敏感数据:审计日志只记入参摘要与哈希,不记原始 SQL 与文件内容;
content里的密钥、token 统一脱敏。 - 能力声明与实际不符:
capabilities里没声明的原语不要实现;上线前用官方 SDK 的 Client 跑一次initialize加tools/list冒烟。
五、结语
MCP 的生产化,本质是把"协议能跑"升级为"能力可治理":会话可恢复、并发可限流、调用可审计、故障可定位。建议的落地顺序是:先用 Streamable HTTP 加会话 ID 打通多实例部署,再补并发隔离与超时取消,最后接入指标、追踪、审计三件套。协议规范只是起点,真正决定 Agent 平台稳定性的是 Server 侧的工程纪律。

发表评论 取消回复