Swagger（现在叫 OpenAPI）可能是过去十年最成功的 API 描述标准。它解决了一个核心问题：让前后端团队能够基于同一份契约进行并行开发。通过标准化的 JSON/YAML 描述，API 文档、客户端 SDK、Mock 服务都可以自动生成，极大地提升了研发效率。
但 Swagger 的设计目标是”让人类开发者理解 API”。它描述的是接口的结构——路径、参数、类型、返回值——但不描述接口的语义和使用场景。对于人类来说，看一眼参数名和注释就能理解这个接口是做什么的，但对于 AI Agent 来说，这些信息远远不够。
Model Context Protocol（MCP）的出现，本质上是为 AI Agent 提供了一种理解和调用工具的标准方式。如果说 Swagger 回答的是”这个 API 怎么调用”，那 MCP 回答的是”在什么场景下应该调用这个工具，以及如何将结果整合到对话上下文中”。
MCP 的设计包含几个关键概念：Tools（可执行的操作）、Resources（可读取的数据源）和 Prompts（预定义的交互模板）。相比 Swagger 纯粹的接口描述，MCP 额外提供了丰富的语义信息，让大模型能够在对话过程中自主判断何时调用哪个工具。
传统的 API 消费方式是”人写代码调接口”——开发者阅读文档，编写客户端代码，处理各种边界情况。但在 AI Agent 的场景下，API 的消费者变成了大模型。这意味着 API 的设计需要从”对人友好”转向”对人和 AI 都友好”。
在实际落地中，我们发现一个有效的渐进策略：先将现有的 OpenAPI 文档转化为 MCP 的 Tool 定义，补充必要的语义描述和使用示例，然后逐步积累 AI 调用的反馈数据来优化描述的准确性。服务端同学不需要改动任何业务逻辑，只需要在 API 描述层多做一步”翻译”工作。这个成本很低，但收益是让整个内部服务体系都能被 AI Agent 调用。
长远来看，Swagger 和 MCP 并不是替代关系，而是互补关系。OpenAPI 仍然是前后端协作的基础，MCP 则在此之上为 AI 消费场景提供了额外的语义层。未来的 API 管理平台大概率会同时支持两种协议的描述和生成，让同一个服务既能被人类开发者调用，也能被 AI Agent 发现和使用。