一、对比背景:为什么需要”模式 vs 反模式”这把尺子
某AI研究机构于2024年11月发布模型上下文协议(MCP)后,社区在几个月内就涌现出成百上千个MCP Server。文件系统、数据库、SaaS接口、浏览器自动化都被包了一层MCP外壳。这与当年某类编辑器语言服务协议首次出现时的情况相似:一旦接口标准化,实现数量会迅速膨胀。
与编辑器语言服务不同的是,MCP的服务端面向的是大模型Agent。Agent的上下文预算有限,工具名和描述占满了上下文,Agent就难以分辨哪些工具真正可用。因此MCP Server的设计问题不只是”功能对不对”,还涉及”Agent能不能选对”。协议规范规定了Server对外暴露什么,却几乎不涉及Server自身如何组织。
工程实践最先遇到问题的是几类运营方:
- Agent编排平台: Agent需要来自多个MCP Server的能力,但客户端能维护的连接数有限。
- 统一治理团队: 运营方需要跨一批Server做统一认证和日志审计。
- 工具设计者: 一个工具塞几十个参数、状态该放哪里全靠感觉、聚合多个上游服务时工具名互相冲突,都是社区反复踩过的坑。
所以,本文的对比对象很明确:一类是研究中归纳出的五类可复用架构模式,另一类是社区常见的四个反模式。前者告诉我们”把Server设计成什么样”,后者告诉我们”哪些设计会把Agent的能力边界拉低”。评判标准只有一个:在真实Agent调用中,工具能否被正确选择、正确填充参数,以及出问题时能否被定位。
二、对象定义与研究方法:对比结论从哪来
先分别说明两个对比对象的基本含义。
架构模式来自软件工程中的”模式描述法”,按上下文、问题、解决方案、结果四要素书写。可以理解为:在某种前提下反复出现的结构化解法。它说明在什么约束下,采用哪种Server结构,以及这样会带来哪些收益与代价。
反模式则是看似合理、实则反复引发故障的做法。以参数膨胀为例,每个参数看起来都合理,组合起来却会拖垮Agent的工具选择。
需要说明的是,原文未逐项给出具体命名,以下内容结合语料库中的场景描述,用中性命名整理,便于逐维对比。
这套结论之所以可供参考,关键在于研究方法:
- 语料库: 包含5个来自某语音AI平台真实生产环境的Server,覆盖工具编排、会话状态、电话适配、客户关系管理网关、多租户聚合等场景;另有10个来自某官方公开仓库的常见Server,涉及文件系统、关系型数据库、代码托管、团队协作通讯、浏览器自动化、记忆等。生产Server与公开Server兼顾,避免了只用演示代码下结论。
- 两阶段编码: 先做开放编码,标注每个Server中反复出现的结构性决策;再做模式编码,归并成候选模式。只有同时满足两个条件,候选才会正式进入模式目录:至少在两个独立Server中出现;解决的是没有现成方案的问题。
- 留出验证: 另外54个未参与归纳的Server,交给两个独立的通用大模型评审员分类。评审员只拿到模式定义,且描述中刻意不提及架构。两者一致性系数(Cohen’s kappa)为0.76,属于”实质性一致”。
kappa能控制在0.76,说明模式边界足够清晰,普通工程师也能据此做出基本一致的判断,而不是需要作者才能理解的内部分类。
三、五种可复用架构模式
模式A:直通代理型(Passthrough Proxy)
- 上下文: 上游已经提供完整API,如文件系统、关系型数据库、代码托管、团队协作工具,目标是”让Agent用上它”,而非重新定义业务。
- 问题: Agent只能调用工具,不能直接访问HTTP接口或SQL。若每个项目各自包装,接口命名、参数风格、错误码会各不相同,模型难以形成稳定的使用习惯。
- 解决方案: 遵循上游API的语义做薄封装。工具名与上游资源一一对应,参数直接映射,只补充面向模型的描述与错误说明。
- 结果: 实现成本最低,上游变更容易同步,是公开Server中最常见的一类。代价是Server几乎没有抽象,上游有多少端点,就暴露多少工具。因此通常只服务单一上游,需要配合工具发现或检索式路由(见第六节)。
- 设计要点: 用统一的错误格式把上游错误翻译成模型能理解的提示,例如”参数不合法”还是”权限不足”,避免把原始堆栈直接抛给模型。
- 上下文: 典型见于语音AI生产场景。Agent需要完成的是多步任务,如”查询客户信息→判断资格→创建工单→告知结果”,涉及多个内部或外部系统。
- 问题: 如果让模型自行编排,需要多轮推理、反复调用工具,延迟和失败率都会上升。每一步的错误还会累积,并且很难定位。
- 解决方案: 把高频多步流程封装为一个”工作流工具”。Server内部按固定顺序调用多个上游,中间结果留在服务端,只向模型暴露必要的输入与输出,失败时返回结构化的失败原因。
- 结果: 大幅减少模型的推理轮次,流程可测试、可重放。代价是流程一旦写死,灵活性下降;新流程需要改代码、发版本,而不是提示词调整。
- 边界: 流程稳定且调用频次高的任务,适合固化为编排工具;探索性强、步骤不确定的任务,保留细粒度工具反而更合适。
模式C:会话状态型(Session-Aware / Stateful)
- 上下文: 语音助手、客服机器人等场景,需要在一个会话内保留上下文,如已识别的意图、已收集的槽位、待确认的订单。
- 问题: MCP的工具调用本身是无状态的。如果每轮都把全部历史塞进上下文,token成本随轮次线性增长,还会把无关的过期信息带进决策。状态若只放在Server内存里,进程重启或多实例部署时会话就会丢失。
- 解决方案: 由Server显式管理会话状态。以会话标识为键,把状态存到外部存储(如带过期时间的键值存储),按会话粒度设置生存期(TTL)与清理策略,工具只接收”增量输入”,返回”决策所需的最小结果”。
- 结果: 上下文更短、成本更可控,会话可跨实例恢复。代价是引入新的依赖:状态存储、会话生命周期管理、状态版本兼容,以及相应的容量规划。
- 边界: 一次调用即可完成的工具型服务,不需要这一层;引入前要明确状态存放位置和清理策略,否则会从”无状态”滑向”难以运维的有状态”。
模式D:协议适配型(Protocol Adapter)
- 上下文: 语料库中的语音平台需要对接电话信令等专用协议。这类能力不是标准HTTP接口,而是事件流、二进制信令或长连接推送。
- 问题: MCP只认工具调用这一种交互方式,外部世界的异步事件无法直接被模型感知。
- 解决方案: 在专用协议与MCP之间放一层适配器:把外部事件转换成工具可调用的动作,把工具调用的结果再映射回外部协议指令,并在适配层完成超时、重试与幂等控制。
- 结果: Agent无需理解底层协议细节即可操作专用设备或系统。代价是适配层成为故障集中点:协议版本变化、连接抖动、重复事件,都需要在这里兜住。
- 设计要点: 工具语义应面向业务动作(如”发起通话””转接人工”),而不是照搬协议原语,否则模型会被底层术语干扰。
模式E:多租户聚合型(Multi-tenant Aggregation)
- 上下文: 平台方需要给多个业务方或客户统一提供一批能力。单个Agent需要的工具来自多个Server,而客户端连接数有限;同时运营方需要统一认证与审计。
- 问题: 直接让客户端连多个Server,会导致连接数膨胀、认证逻辑在每个客户端重复实现、日志分散无法关联。
- 解决方案: 在客户端与上游Server之间放一个聚合层,它对外表现为一个Server,对内维护到各上游的连接池,统一完成身份认证、租户识别、限流、调用日志与审计埋点。
- 结果: 客户端只维护一条连接,认证与审计集中管理,上游故障可以在聚合层做降级或熔断。代价是聚合层成为关键路径,对容量、可用性和可观测性的要求最高。
- 边界: 租户数量少、内网可信环境里,这一层带来的复杂度可能大于收益。
五种模式可以组合。例如一个面向语音客服的Server,可能是”会话状态型 + 工具编排型 + 多租户聚合型”的叠加。选择时真正要回答的是:我的约束条件落在哪一类。
四、四个应该避免的反模式
反模式与模式并非对立的两组清单,而是同一组设计决策的两端:把某个维度的做法推过头,就会从模式滑向反模式。下面逐一对照说明。
反模式1:工具参数膨胀 ← 直通代理型的过度使用
把上游API的全部字段原样映射为工具参数,一个工具塞入几十个参数,并配上冗长描述。结果是工具定义本身挤占上下文,模型在填充参数时更容易漏填、错填,可选参数太多也增加了误用空间。
正确做法: 按使用频度拆分参数。高频必填项保留为工具级参数,低频项收进一个配置对象;同时提供”默认配置 + 覆盖项”的调用方式。
# 不推荐:把上游所有字段平铺成工具参数# create_deployment(env, region, replicas, image, cpu, memory, disk,# timeout, retry, health_check_path, labels, annotations, ...)# 推荐:核心参数显式化,其余收进一个配置对象def create_deployment(target: str, spec: dict | None = None) -> dict: spec = spec or {} return { "replicas": spec.get("replicas", 1), # 有默认值的项无需模型决定 "timeout": spec.get("timeout", 30), }
反模式2:单Server职责堆积 ← 直通代理型无序扩张
一个Server先后接入文件系统、数据库、代码托管、通讯工具,工具数量从十几个涨到上百个。工具名失去统一命名空间,描述风格各异,模型面对几十个语义相近的”查询”类工具时选择准确率明显下降,运维上也无法判断某个故障来自哪一类上游。
正确做法: 按上游边界或业务域拆分Server;同一聚合层内用命名空间前缀区分来源;对工具数量做显式预算。
反模式3:语义重叠与命名冲突 ← 多租户聚合型缺乏治理
聚合多个上游时,不同上游暴露同名工具,如多个系统都有search、list、get。模型无法判断该调用哪个,或者随机命中一个错误实现,而且这种错误通常不报错,只表现为结果不对,极难排查。
正确做法: 强制命名空间(如crm.search与wiki.search),冲突时按明确规则消歧;对功能重复的工具做合并,保留一个入口;给每个工具写清楚”什么时候不该用它”。
# 注册工具时强制带命名空间前缀def register(registry, namespace, name, handler, description): key = f"{namespace}.{name}" if key in registry: raise ValueError(f"duplicate tool: {key}") # 注册期暴露冲突,而非运行期 registry[key] = (handler, description)
反模式4:状态无处安放或藏起来 ← 会话状态型的反面
两种表现:一是该有状态的会话把全部历史塞进上下文,成本随轮次膨胀;二是不该有状态的工具内部藏了全局变量,多租户或并发调用时相互串扰,甚至把A租户的数据返回给B。
正确做法: 显式决定状态位置。会话级状态放外部存储并带TTL,请求级中间态只在单次调用内传递,工具实现保持可重入。任何跨调用共享的数据都必须有明确的隔离键。
这四个反模式的共同点值得注意:它们几乎都不是”能力不够”,而是”边界没定”。这正好解释了为什么模式与反模式必须成对讨论。
五、核心差异对比表
| 对比维度 |
A 直通代理型 |
B 工具编排型 |
C 会话状态型 |
D 协议适配型 |
E 多租户聚合型 |
| 核心目标 |
让Agent用上已有API |
把多步流程收敛为一次调用 |
跨轮保留会话上下文 |
把非标准协议接入MCP |
统一连接、认证与审计 |
| 状态位置 |
基本无状态 |
单次调用内 |
外部状态存储 |
适配层连接状态 |
聚合层连接池 |
| 实现复杂度 |
低 |
中 |
中高 |
中高 |
高 |
| 新增依赖 |
几乎无 |
上游服务 |
状态存储 |
协议SDK/长连接 |
连接池、鉴权、日志 |
| 工具数量趋势 |
随上游端点线性增长 |
少量粗粒度工具 |
少量 |
面向业务动作,数量少 |
汇聚多Server,数量最多 |
| 关键风险 |
工具膨胀、参数过多 |
流程僵化、改动需发版 |
状态泄漏、容量增长 |
适配层成为故障点 |
聚合层成为关键路径 |
| 可观测性要求 |
中 |
中(需链路追踪) |
高 |
高 |
最高 |
| 典型场景 |
文件系统、数据库、代码托管 |
语音客服、工单流转 |
多轮对话、表单收集 |
电话信令、设备控制 |
平台化对外提供能力 |
| 主要代价 |
抽象不足 |
灵活性下降 |
运维复杂度上升 |
耦合外部协议 |
建设与运维成本最高 |
与之对应的反模式识别信号,可以直接用于评审:
| 反模式 |
早期信号 |
后果 |
修正方向 |
| 工具参数膨胀 |
单个工具参数量超过常用字段数,描述篇幅远超逻辑 |
参数漏填错填,上下文被挤占 |
拆分参数、提供默认配置 |
| 职责堆积 |
一个Server的工具横跨多个无关业务域 |
选择准确率下降,故障难定位 |
按域拆分Server |
| 语义重叠/命名冲突 |
多个工具描述相近,出现同名 |
静默调错,难以排查 |
命名空间、工具合并、消歧规则 |
| 状态错位 |
状态存在进程内存或无隔离键的全局变量 |
重启丢失、跨租户串扰 |
外部存储+TTL、显式隔离键 |
六、延伸对比:工具数量与选择准确率的取舍
原文用真实生产遥测回答了一个此前只能靠猜测的问题:一个MCP Server里到底能放多少工具。结论不能简化为一个固定数字,因为影响准确率的不只是数量,还有三项:
- 语义正交度: 工具之间功能越重叠,区分难度越高。20个职责清晰的工具,可能比10个语义相近的工具更容易选对。
- 描述质量: 工具描述决定了模型判断的依据。写清输入前提、输出含义和”不适用场景”,比增加数量更能提升准确率。
- 呈现方式: 把全部工具定义一次性放入上下文,与先做检索再注入相关工具子集,准确率表现差别明显。
因此更实用的做法是把”数量上限”换成一组可观测指标:工具选择错误率、平均调用轮次、参数缺失或校验失败率、无效调用占比。以这些指标在灰度环境做压测,再确定自己的Server该拆还是该合,比套用别人的数字可靠。
据此可以形成一个取舍逻辑:
- 偏好少而精(编排型): 适合高频、路径固定的任务,准确率与延迟更可控,代价是灵活性。
- 偏好多而全(直通型): 适合长尾、探索性需求,覆盖面广,代价是需要配合检索路由和良好的命名规范,否则准确率会随工具增长而下降。
七、相同点分析:模式与反模式共享的设计约束
尽管方向相反,五类模式与四类反模式处理的其实是同一组问题,这也是它们能被放进同一张对照表的原因:
- 共同边界问题: 都在回答”Server的职责边界划在哪里”。模式给出的是一个受控的边界,反模式则是边界失控后的形态。
- 共同状态问题: 都在回答”状态放在哪、活多久”。会话型模式与状态错位反模式是同一决策的两面。
- 共同抽象问题: 都在回答”暴露多少、以什么粒度暴露”。直通型与参数膨胀、职责堆积的差别只是抽象程度是否被有意控制。
- 共同可观测性问题: 无论采用哪种模式,若缺少调用日志、耗时分布和失败分类,问题都只能在用户投诉后才发现。
- 共同约束: 都要在有限上下文、有限连接数、有限运维人力三重约束下工作。
八、典型场景选择
- 开发测试与个人效率: 优先直通代理型,快速接入文件系统、代码托管等已有API,不引入额外依赖。
- 企业内部系统集成: 以聚合型作为统一入口,对外收敛认证与审计,对内按业务域拆分为多个直通或编排型Server。
- AI语音与实时交互: 会话状态型叠加编排型,把多步业务流程固化,同时用外部状态存储控制上下文长度。
- 设备与专有系统控制: 协议适配型,适配层承担超时、重试与幂等,工具语义对齐业务动作。
- 多租户对外服务: 聚合型为主,配合租户级限流与调用审计,避免把上游凭证直接暴露给客户端。
- 探索型Agent与长尾工具需求: 直通型配合工具检索,宁可工具多,也要靠检索与命名规范控制误选。
九、选型建议
- 先定约束,再选模式: 约束通常只有三类:连接数是否紧张、是否需要统一认证审计、任务是否高频固定。三类都不涉及,直通型起步即可。
- 不要一次性叠加模式: 每加一层都要评估运维成本。状态存储、聚合层都会引入新的故障点。
- 工具数量当作预算来管: 为单个Server设定工具数量与描述长度的上限,超限时先考虑拆分而不是继续堆叠。
- 把准确率纳入验收: 在预发布环境用真实调用样本统计选择正确率,比人工评审Server代码更能发现问题。
- 状态要么显式外置,要么明确不留: 避免出现”看起来无状态、实际有隐藏状态”的实现。
- 治理能力强时优先考虑聚合层: 若团队已有统一的日志服务、监控告警、身份认证与密钥管理能力,聚合层的边际成本较低。若团队规模小、服务数量少,可以先做直通型加简单网关。若使用云上资源,可借助容器平台部署Server,用负载均衡承接流量、对象存储保存会话产物、日志服务与监控告警做统一观测,身份认证使用统一认证能力;百度智能云等主流云服务商均提供这几类基础能力。
十、迁移与使用注意事项
从一种模式迁移到另一种,或从反模式形态整改,风险集中在以下几个方面:
- 接口兼容: 工具名与参数结构变更会直接影响已有Agent的提示词与调用链。建议保留旧工具作为过渡别名,并标注弃用周期。
- 会话与数据迁移: 引入外部状态存储时,旧会话标识需要映射规则;有状态转无状态时,要确认哪些上下文可以丢弃。
- 权限与隔离: 聚合层集中认证后,必须确认租户级授权在每一跳都被传递,不能只在入口校验一次。
- 稳定性: 新增的中间层要配置超时、重试上限与熔断策略,避免上游抖动被放大为雪崩;编排型工具要保证失败时可重放。
- 可观测性: 迁移前先埋好调用链标识,让一次Agent调用能贯穿客户端、聚合层与上游Server,否则跨层问题无法定位。
- 容量规划: 工具定义体积、会话状态存储增长、聚合层连接池大小,都需要按预期调用量做估算并留出余量。
- 版本升级: Server自身版本与协议版本的兼容矩阵要提前确认,灰度发布并按租户维度分批切换。
十一、总结
回到对比主题。五类模式与四个反模式并非互斥清单,而是同一组设计决策的两种结果:直通代理型胜在实现成本最低,代价是抽象不足,容易滑向参数膨胀与职责堆积;编排型与会话状态型用少量粗粒度工具换取可控的准确率和上下文成本,代价是灵活性与运维复杂度;协议适配型解决的是”外部世界不是HTTP”的问题;多租户聚合型解决的是连接数、统一认证与审计的治理问题,代价是自身成为关键路径。反模式则集中提醒:工具数量不是能力指标,状态必须有明确归宿,同名同义工具必须消歧。
据此形成选型路径:先识别自己受限的是连接数、治理能力还是任务确定性;再从对应模式起步,按需叠加;最后用工具选择准确率、调用轮次和失败分布这些可观测指标,持续验证Server设计是否还成立。这样的顺序,比先选架构再补理由更稳妥。