从 OpenAPI 到生产可用的 MCP 服务

把 HTTP API 接给 AI，最容易跑通的是调用，最容易留下隐患的却是权限、凭证和后续变更。这篇指南的核心建议是：已有 OpenAPI 文档的服务，应优先从契约生成 MCP server，再围绕工具范围、认证、测试和版本兼容建立约束。

它值得读的地方，是把「模型能调用接口」推进到「团队能长期维护」。不过，原文更像一份实践路线图，没有给出完整实现、性能测试或方案对照，部分推荐还需要结合自己的系统判断。

已有 OpenAPI，为什么还要手写工具包装？

MCP（Model Context Protocol）提供一种标准协议，让兼容的 AI 客户端发现并调用外部工具。服务器暴露的工具带有类型化输入结构，调用后返回模型可以继续处理的结果。它还可以提供 resources 和 prompts，能力并不限于执行接口。

原文把 MCP 与 function calling、plugins 放在一起讨论，关注的是如何减少应用与工具之间的硬编码；同时提醒，A2A 讨论的是智能体之间的协作，MCP 关注的是智能体访问工具和数据，两者解决的问题不同。

对于已有 HTTP API 的团队，作者推荐从 OpenAPI 契约生成 MCP server，而不是为每个操作手写一层包装。原因很直接：接口参数更新了，包装层忘记同步，模型看到的工具定义就可能和真实接口脱节。

把 MCP server 当作构建产物，才有机会让工具定义跟着 API 一起更新。

这里的「契约」就是机器可读的接口约定。生成流程负责把这些约定映射为工具，并在规范变化时更新工具列表。作者甚至主张，手写服务器应当成为例外。

但生成只解决了一部分问题。OpenAPI 是否准确、参数描述是否清楚、返回结构是否足以支持下一步操作，仍然决定了工具的质量。原文没有提供生成器配置，也没有演示复杂接口如何映射，不能据此认定所有 API 都能直接生成可用工具。

工具能暴露多少，应该由权限决定

作者反对把整份 OpenAPI 的所有端点都交给模型，给出的具体建议是：先暴露三个操作，而不是整个 API。

理由有两层。工具定义会占用模型有限的上下文；工具越多，智能体能够采取的行动也越多，其中可能包括它根本不该执行的操作。原文建议按智能体分配工具集合，通过 hub 控制不同智能体能看到什么。

这里的「三个」是收缩范围的示例，原文没有实验说明三个操作就是最优数量。真正需要确定的是：完成当前任务，最少需要哪些能力？

认证则要独立处理。远程 MCP server 需要真正的身份认证，原文建议使用 OAuth2，并把上游 token 留在 gateway 中，不要放进提示词或 MCP JSON。上游 base URL 也应由网关集中固定，避免依赖智能体提示词来约束访问目标。

权限不能停留在网关入口。密钥应按角色划分，支持单独撤销某位成员的访问，而不是全团队共用凭证，或者为了移除一个人更换整个 MCP URL。上游服务仍要执行自己的授权检查。

不要把模型的自我约束当作权限边界。

工具结果也可能包含提示注入，即返回内容夹带诱导模型执行额外操作的指令。作者要求按 MCP 层不可信的前提保护上游。工具可见范围、身份权限和服务端授权，需要共同限制最终能发生什么。

部署方式不同，维护责任也会跟着变

本机单用户场景，stdio 足够简单。工具需要多人共享、供浏览器中的客户端使用，或者需要集中认证时，作者推荐远程 HTTP，并明确偏向为共享工具使用 streamable HTTP。

这不是单纯的传输方式选择。远程化之后，认证、限流和服务运维都要有人负责。对于内部 API 和多个上游服务，作者建议考虑 gateway：统一聚合服务、处理认证与限流，也让智能体不必了解内部网络拓扑。

因此，托管 gateway 可能比自己维护一个 Node 进程省事。但原文没有给出费用、延迟、可靠性或部署约束的对照，无法据此判断托管方案一定更划算。

另一个容易遗漏的问题是兼容性。智能体虽然会在运行时发现工具，已有工作流仍可能依赖工具名称和输入结构。重命名工具、收紧参数要求，都可能让原本可用的流程失效。原文提出要安全地做版本管理，却没有展开具体迁移策略，这部分需要团队另行设计。

测试可以先沿用验证 API 的思路：列出工具，用文档中的输入调用，再检查结果。之后连接真实客户端，例如 Cursor、Claude Code。原文还列出 Claude Desktop、VS Code、Windsurf、Cline、Zed，但没有提供兼容性比较结果。发布时，作者建议把文档与 MCP 服务放到自己控制的域名下。

我的判断

这篇最可靠的建议，是让接口契约、工具范围和权限管理一起进入交付流程。对已有 OpenAPI 的团队，生成工具包装可以减少重复维护；相比逐个手写，更容易建立统一更新机制。

前提是契约本身足够可信。接口文档长期失真，生成流程只会把错误继续传给智能体。对于缺少规范、需要特殊业务编排的接口，原文没有证明生成方式一定优于手写包装。

也不必因为准备接入 AI，就立刻引入 MCP 和托管网关。单个应用只调用少量固定函数时，直接使用 function calling 仍是可比较的路径；多个兼容客户端需要共享工具时，MCP 的标准接口才更有吸引力。这是基于使用范围的取舍，原文没有提供两者的成本对照。

此外，文章最终导向 Powerduck，并将其定位为 local-first、OpenAPI-first 的工作空间，覆盖调试、测试、mock 和智能体工具。这让托管与契约生成的推荐带有明确的产品导向，可以参考，但不能当作独立评测。

能拿来做什么

• 如果团队已有 OpenAPI，先选三个边界清楚的操作生成工具，验证定义、输入和实际返回是否一致，再决定是否扩大范围。
• 给 Cursor 或 Claude Code 接入内部 API 前，先确定角色权限、凭证存放位置和单人撤销方式，并确认上游服务仍会检查授权。
• 本机个人使用可以先选 stdio；多人共享时，再评估 streamable HTTP、集中认证，以及自建 Node 服务和托管 gateway 各自的维护责任。
• 修改工具名称或参数要求时，把现有智能体工作流纳入验证；至少完成工具枚举、文档输入调用、结果检查和真实客户端连接。