我们构建了 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 的工具分为几类：

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

每个生成的工具都拥有：

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

渐进式披露 (Progressive Disclosure)

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

Agent 可以：

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

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

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

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

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

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

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

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

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

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

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

四个结构性问题

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

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

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

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

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

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

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

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

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

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

每个工具背后都有：

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

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

用户的问题可能只有 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 需要处理：

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

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

各方都深受其苦。

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

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

一个测试场景涉及：

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

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

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

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

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

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

根本原因

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

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

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

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

我们的教训

转型

这一认识促使我们提出了一个不同的问题：

如果 MCP 不是 Agent 赋能的最终答案，那么什么是？

我们并没有否定 MCP 的价值——它提供了标准化的连接，这对生态系统很重要。但我们需要一种能够实现以下目标的方案：

• 表达工作流，而不仅仅是工具
• 引导 Agent 完成序列操作
• 在写入前进行校验
• 强制执行工程质量门禁
• 将复杂性吸收进系统内部

我们得出的答案是：CLI + SKILL。

在下一篇文章《为什么我们要开发全新的 Apifox CLI》中，我们将探讨这种架构转型——复杂性如何从模型上下文转移到工程系统，以及为什么这会改变 Agent 赋能的一切。

核心要点

• MCP 成为“Agent 如何连接工具”的行业标准答案。
• 我们构建了 126 个 MCP 工具，原以为工具越多 = 赋能越强。
• 实际任务揭示了四个结构性问题：发现成本、上下文侵占、会话开销、产品语义。
• 根本原因：MCP 连接工具，但复杂任务需要可执行的流程。
• 当工具描述消耗上下文时，更多的工具是一种成本，而非收益。

下载 Apifox，在一个工作区内完成 API 设计、Mock、测试和文档工作。了解更多关于 Apifox CLI 的信息，用于命令行 API 测试、CI 自动化和 AI Agent 工作流。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。