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 侧的工程纪律。

点赞(0) 打赏

评论列表 共有 0 条评论

暂无评论
立即
投稿

微信公众账号

微信扫一扫加关注

发表
评论
返回
顶部