我们构建了 126 个 MCP 工具，但这并不是 Agent 的最佳方案

当 MCP 成为行业热点时，我们构建了一个包含 126 个自动生成工具的完整 MCP Server。以下是出现的问题，以及为什么更多的工具并不意味着更好的 Agent 赋能。

MCP 热潮

2025 年初，MCP (Model Context Protocol) 成为行业热点。

Anthropic 推出了该协议。Cursor、Claude Code、Antigravity、各种 Agent IDE 以及众多 SaaS 产品迅速跟进。该协议承诺为 AI Agent 连接外部工具和数据源提供一种标准化的方式。

在那段时间里，几乎每个拥有 API 的产品都会被问到同一个问题：

“你们支持 MCP 吗？”

对于 Apifox 来说，这个选择似乎顺理成章。

为什么 MCP 看起来是标准答案

Apifox 自身已经积累了全面的 API 开发能力：

API 文档
Schema 定义
Mock 服务器
测试用例 (Test cases)
测试场景 (Test scenarios)
测试套件 (Test suites)
测试报告
导入/导出工作流
分支协作
以及更多

如果 Agent 将成为新的软件入口——用户与产品交互的新方式——那么通过 MCP 暴露这些能力似乎是一张必须拿到的入场券。

我们相信，如果我们能将能力封装为 MCP 工具，Agent 将能够：

查询 API 文档
创建测试用例
运行测试场景
导入/导出项目数据
管理环境和变量
跨分支协作

逻辑非常直接：暴露的能力越多 = 对 Agent 的赋能越强。

我们实际构建了什么

我们对此非常重视。

Apifox MCP 并不是一个只有几个手写端点的简单 Demo。它是一个完整的 MCP Server：

会话系统 (Session System)

MCP 客户端首先初始化一个会话。服务器生成一个 sessionId 并通过 Redis 保存会话状态。后续请求继续携带 sessionId 进行访问。

换句话说，它不是一次性的 HTTP 调用，而是一个协议级的会话系统。

工具分类

工具层也不是手写的几个固定端点。我们将 Apifox 的工具分为几类：

类别	描述	示例
原生项目工具	为项目级操作构建	项目摘要、目录结构、资源详情
内置领域工具	Apifox 核心功能	导入/导出、接口详情、测试用例、测试场景
生成的 OpenAPI 工具	从 OpenAPI 定义自动转换	126 个具有唯一标识符、路径、HTTP 方法和输入 Schema 的工具

最后一类：126 个生成的工具。

每个生成的工具都拥有：

唯一的标识符
特定的 API 路径
HTTP 方法（GET, POST, PUT, DELETE 等）
完整的输入 Schema，包含字段描述、类型和枚举值
定义的返回结构

渐进式披露 (Progressive Disclosure)

为了减轻工具暴露的压力，我们还构建了一个动态发现层：

Agent 可以：

首先搜索可用的接口工具 (listOpenApiEndpoints)
然后获取特定工具的 OpenAPI 详情 (getOpenApiDetails)
最后通过工具 ID 执行实际的 HTTP 调用 (executeOpenApi)

这是我们在渐进式披露方面的尝试。我们没有简单地直接、显式地暴露所有底层端点。我们希望 Agent 先搜索，再获取详情，最后执行。

随机工具之墙 (The Wall of Random Tools)

但在进入实际任务时，问题很快就出现了。

考虑一个简单的用户请求：

“帮我为这个接口添加一个测试并运行验证。”

从实现的角度来看，这是一个合理的请求。Apifox 具备以下能力：

查找接口
创建测试用例
运行测试场景
生成报告

但从 Agent 的角度来看，这个简单的请求实际上触发了一系列连续的判断：

决策点	选项	不确定性
从哪里开始？	先找项目？还是先找接口？	缺乏明确引导
该读取什么？	读取接口详情？还是列出已有用例？	两者看起来都合理
如何创建？	直接用 `createTestCase`？还是先找用例分组？	需求未知
如何更新？	直接调用 `update` 工具？还是导入步骤后再读回？	隐藏的工作流

Agent 不仅仅需要找到正确的工具。它需要先解决“使用哪个工具”的问题，然后才能开始解决用户的问题。

从实现角度看，这些问题都可以通过工具解决。但从 Agent 体验的角度看，它们构成了一道“随机工具之墙”。

四个结构性问题

通过实际测试和内部反馈，我们发现了 MCP 方案的四个结构性问题。

问题 1：工具发现成本飙升

Apifox 不是一个仅用十几个端点就能描述清楚的产品。

模块	细分
接口 (Endpoints)	列表、获取、创建、更新、删除
数据模型 (Schemas)	列表、获取、创建、更新、删除
环境 (Environments)	列表、获取、创建、更新、删除、变量
Mock	配置、启用、禁用
测试用例 (Test cases)	列表、获取、创建、更新、删除、复制
测试场景 (Test scenarios)	列表、获取、创建、更新、删除、导入步骤、运行
测试套件 (Test suites)	列表、获取、创建、更新、删除
报告 (Reports)	列表、获取、生成、下载
导入/导出	多种格式、选项
分支 (Branches)	列表、创建、合并、删除

当工具从十几个增长到几十个或上百个时，Agent 在开始解决用户问题之前，必须先解决“该用哪个工具”的问题。

我们尝试将工作流写入工具的 description（用于向 AI Agent 暴露工具的字段）。例如，工具描述会明确指出：

“在查询接口数据之前，你需要先通过另一个工具确认项目，然后通过第三个工具获取项目元数据，最后调用当前工具。”

这种方法在小规模工具集中有效。但在海量的工具墙中，description 本身就在竞争模型的注意力。

我们在描述中写的引导越多，消耗的 Token 就越多——而 Agent 实际阅读并遵循它们的可能性就越小。

问题 2：业务 Schema 侵占上下文

每个 MCP 工具不仅仅是一个工具名称。

每个工具背后都有：

description（工具的作用）
input schema（参数、类型、必填/选填）
字段解释（嵌套结构、约束）
枚举值（允许的选项）
返回结构（响应格式、错误处理）

让我们做一个保守的估计：

因素	数值
工具数量	100+
每个工具平均 Token 数	~500
总工具描述 Token 数	~50,000

用户的问题可能只有 50 个字符。但模型被迫首先引入 50,000 个 Token 的工具描述——这仅仅是为了一个 MCP Server。

这并非理论推测。行业数据支持这一点。

Cursor 的官方博客文章 "Dynamic Context Discovery" 提供了宝贵的参考数据：通过将 MCP 工具描述、终端会话和长对话转换为按需加载的上下文，运行时 Token 消耗减少了 46.9%。

Trae 的做法更为直接：限制 MCP 工具数量和单个工具描述长度：

工具数量上限：40
单个工具描述限制：8000 字符

事实上，在早期的内部测试中，许多团队反馈 Apifox MCP 在 Trae 中存在部分工具无法被调用的问题。由于模型上下文有限，Agent 被迫做出权衡，而外部工具往往是首个被“砍掉”的对象。

这些解决方案都指向同一个事实：

工具描述不能无限地进入模型上下文。

问题 3：协议会话让执行链变重

Apifox MCP server 需要处理：

协议状态	描述
MCP initialize	客户端与服务器之间的握手
sessionId generation	会话的唯一标识符
Redis session storage	状态持久化
Transport connect/close	连接管理
Session touch	保活机制
DELETE session	完成后的清理
JSON response 或 SSE 配置	输出格式选项

对于简单的工具调用，这些成本是可以接受的。但对于具有大量调用和频繁探索的 Agent 任务，这些状态管理要求增加了服务器端和客户端的复杂性。

在实现 Apifox MCP 时，团队耗费了大量精力来排查和适配不同的 Agent 客户端（Cursor, Claude Code, Antigravity, Trae 等）。然而，协议兼容性问题依然存在，且官方 MCP 协议仍在不断发布新版本补丁。

各方都深受其苦。

问题 4：原子化工具无法自然表达产品语义

在 Apifox 的测试场景中，它不仅仅是一个简单的 steps 数组表达式。

一个测试场景涉及：

组件	复杂性
导入 (Import)	来自接口或已有用例的步骤
回读 (Read-back)	导入后获取完整结构
内部用例 (Internal cases)	嵌入在步骤中的 HTTP 请求
前/后置处理器	请求前后的脚本
断言 (Assertions)	响应验证规则
变量提取	从响应中捕获值
运行时环境	环境选择、变量
报告验证	检查测试结果

在将这些拆分为多个 MCP 工具后，Agent 仍需亲自承担测试编排工作。

工具越原子化，模型就越需要理解产品内部语义：

为什么导入需要回读？
为什么内部用例有不同的更新标记？
为什么断言需要特定的比较器？
为什么变量提取有类型约束？

这显然超出了模型的能力范围。

这迫使 Apifox 团队不得不针对内部产品语义主动进行技术工程调整。原子化的端点被动地增加了一个转换层，仅仅是为了适配单个 MCP 工具层的调度。

工程挑战和后期维护成本无疑是艰巨的。

根本原因

这四个问题的根本原因是一致的：

MCP 擅长连接工具，但复杂的研发任务需要的不仅仅是工具连接——它们需要可执行的工程流程。

MCP 优势	MCP 局限
标准化连接	无法表达工作流
统一协议	无法引导顺序
工具暴露	无法强制校验
动态发现	无法提供判断

对于只有十几个定义明确的操作的简单产品，MCP 表现良好。Agent 可以合理地猜测正确的工具，调用它并获得结果。

对于像 Apifox 这样拥有数十个模块、数百个操作、嵌套结构、隐藏工作流和特定产品语义的产品，仅靠 MCP 会产生一道 “随机工具之墙”，让 Agent 难以驾驭。

我们的教训

教训	启示
更多工具 ≠ 更好的 Agent 赋能	工具数量是成本，而非收益
工具描述竞争上下文	每个工具 500 Token × 100 个工具 = 50,000 Token 的负担
会话协议增加执行开销	每次调用都带有协议状态管理
原子化工具需要产品知识	Agent 必须理解内部原理才能进行编排
连接 ≠ 执行	MCP 负责连接；CLI + SKILL 负责执行