将OpenAPI规范转换为MCP工具的实践指南

如果你已经维护了一个 API，你可能已经拥有了创建 MCP 接口所需的大部分信息。

你的 OpenAPI 规范已经描述了：

• 可用的操作；
• 必填和可选参数；
• 响应格式；
• 认证方案。

这项工作不仅仅是给一个 HTTP 端点改个名字。MCP 工具需要能被 AI 客户端理解：它需要一个清晰的名称、准确的描述、有用的输入 schema，以及对底层 API 的受控访问。

本指南通过一个小型工单支持 API 示例来讲解这个映射过程。

OpenAPI 到 MCP：基本映射

一个 OpenAPI 操作可以为一项 MCP 能力提供基础：

具体的呈现方式可能因实现而异，但重要原则是稳定的：工具应该保留 API 的真实契约，而不是将其隐藏在一个模糊的"调用端点"动作背后。

从一个有用的 OpenAPI 操作开始

下面是一个支持 API 的精简但具体的 OpenAPI 示例：

openapi: 3.0.3
info:
  title: Support API
  version: 1.0.0
servers:
  - url: https://api.example.com

paths:
  /tickets/{ticket_id}:
    get:
      operationId: getTicket
      summary: Get a support ticket
      description: Return the status, priority, requester, and latest update for one ticket.
      parameters:
        - name: ticket_id
          in: path
          required: true
          schema:
            type: string
        - name: include_comments
          in: query
          required: false
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Ticket returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Ticket"
      security:
        - bearerAuth: []

  /tickets:
    post:
      operationId: createTicket
      summary: Create a support ticket
      description: Create a ticket for a customer issue.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - description
              properties:
                title:
                  type: string
                description:
                  type: string
                priority:
                  type: string
                  enum: [low, normal, high]
      responses:
        "201":
          description: Ticket created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Ticket"
      security:
        - bearerAuth: []

components:
  schemas:
    Ticket:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        priority:
          type: string
        title:
          type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

这个示例给 MCP 生成器提供了足够的信息来创建两个候选工具：

• getTicket，需要 ticket_id，可以可选接收 include_comments；
• createTicket，需要 title 和 description，接受受限的 priority 值。

API 仍然负责业务逻辑。MCP 添加了一个结构化接口，AI 客户端可以通过它来发现和调用选定的能力。

1. 导入前先验证规范

在将 API 定义作为工具来源之前，先修复它。至少检查：

• 每个操作都有一个唯一且有意义的标识符；
• 摘要和描述解释了操作的作用；
• 参数类型与 API 实际接受的值匹配；
• 必填字段被标记为必填；
• 请求和响应 schema 与真实的 JSON 响应一致；
• 认证方案已记录在案；
• 诸如 #/components/schemas/Ticket 这样的引用能正确解析。

不完整的规范对人类来说可能看起来仍然有效，但会产生令人困惑的工具。缺失的描述、错误标记的可选字段或过时的响应 schema 会给 AI 客户端提供错误的信息，就在它选择操作的那一刻。

0mcp 支持 Swagger 2.0、OpenAPI 3.0、OpenAPI 3.1 和 Postman 集合。对于 OpenAPI 工作流，导入规范而不是将原始 REST 基础 URL 作为来源。0mcp 会验证导入的定义，并在你发布服务器之前显示警告或错误。

有关支持的 OpenAPI 路径的更多细节，请参阅 OpenAPI-to-MCP 文档。

2. 选择应该成为工具的操作

不要因为端点存在就暴露每一个端点。

从一个代表有用工作流的最小集合开始。对于上面的支持 API，这可能是：

• getTicket 用于读取工单当前状态；
• createTicket 用于开启新问题；
• 如果确实需要的话，一个单独的操作用于添加内部备注。

这种选择既是访问控制决策，也是可用性决策。内部管理端点、破坏性操作、调试路由和重复操作不应该自动成为 AI 能力。

HTTP 方法是有用的线索，但它们本身不能决定工具边界。GET 操作可能为工具或资源提供数据，而 POST 操作可能代表一个状态变更工具。要考虑该能力对用户的意义、它需要什么权限，以及 AI 客户端是否能安全地使用它。

在 0mcp 中，你可以审查检测到的操作，并选择要暴露的 API 函数。随着集成变得更加清晰，你也可以创建或更新工具、资源和 prompt。

3. 将参数映射到一个工具 schema 中

HTTP API 将输入分布在多个位置。MCP 工具将输入呈现为一个结构化的 schema。

对于 getTicket 操作：

• ticket_id 来自路径，是必填的；
• include_comments 来自查询字符串，是可选的；
• bearer 凭证用于认证，不作为普通工具参数暴露。

一个概念性的 MCP 工具 schema 可能长这样：

{
  "name": "get_ticket",
  "description": "Return the status, priority, requester, and latest update for one support ticket.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "ticket_id": {
        "type": "string",
        "description": "The ID of the ticket to retrieve."
      },
      "include_comments": {
        "type": "boolean",
        "description": "Whether to include ticket comments.",
        "default": false
      }
    },
    "required": ["ticket_id"]
  }
}

对于 createTicket，请求体变成一个结构化输入，其中 title 和 description 字段是必填的。priority 枚举应该保持为枚举。保留约束有助于 AI 客户端形成一个有效的请求，而不是猜测允许的值。

当路径参数和 body 字段同名时，要 Deliberate 地解决冲突。当 schema 通过 $ref 被复用时，确保生成的工具仍然呈现客户端需要的字段和描述。当 API 使用分页时，清晰地记录游标或分页输入；API 所有者仍然负责分页行为和速率限制处理。

在 0mcp 中，工具名称和描述可以在仪表板中编辑。底层 API schema 应该在原始 OpenAPI 定义中更正，这样 API 契约和 MCP 接口就不会产生分歧。

4. 将认证排除在工具输入之外

该示例使用 bearer 安全方案。这告诉集成方式原始 API 期望如何对请求进行认证，但令牌不应该出现在工具描述、示例 payload 或普通用户参数中。

0mcp 支持 API key、Bearer token 和 OAuth 认证。凭证由用户通过 MCP 客户端在请求时提供，并传递到原始 API。0mcp 不存储这些 API key、Bearer token 或 OAuth 凭证。

你仍然应该应用与 API 本身相同的安全实践：

• 使用最小权限凭证；
• 在暴露写操作之前用 staging 账户测试；
• 避免将 secrets 放在 OpenAPI 描述中；
• 验证每个凭证可以访问哪些操作；
• 审查错误响应中是否有意外暴露的敏感数据。

0mcp Trust 页面解释了平台的凭证传递和数据最小化方法。

5. 导入、配置并创建托管服务器

托管工作流程很简单：

1. 创建一个 0mcp 账户。
2. 导入 OpenAPI 规范。
3. 审查检测到的操作和任何验证警告。
4. 选择要暴露的操作。
5. 当 API 措辞对 AI 客户端不够清晰时，编辑工具名称和描述。
6. 创建 MCP 服务器。

0mcp 托管生成的服务器并提供一个 Streamable HTTP 端点。默认端点格式如下：

yourservername.0mcp.dev/mcp

该端点可以被 MCP 兼容的客户端使用。0mcp 不要求你运行一个本地 stdio 服务器，而且平台目前不支持 local/stdio MCP 服务器。

6. 分享端点之前先测试工具

成功的导入并不能证明生成的工具有用。在连接到生产工作流之前，先在 0mcp Playground 中测试接口。检查可用的能力，用真实输入调用工具，验证认证，并审查各个使用日志。

对于工单支持示例，有用的测试矩阵如下：

还要测试对你的用户重要的失败路径：过期凭证、记录缺失、权限错误、API 超时和验证失败。只在快乐路径上工作的工具还没有为 AI 工作流做好准备。

如果你需要更低级的协议检查，MCP Inspector 指南是应用级测试的有用补充。

7. 为 API 变更做规划

第一次工具调用只是集成的开始。API 会变更，这些变更可能影响：

• 操作名称和描述；
• 认证方案；
• 输入和输出 schema。

当 API 变更时，更新源 OpenAPI 规范，审查受影响的操作，并重新测试工具。在 0mcp 中，配置版本让你可以保存更改、审查更改，并在需要时恢复到更早的配置。保存 MCP 配置会更新托管服务器，无需重建或更改其 URL。

不要假设旧的 MCP 工具仅仅因为名称仍然存在就保持正确。schema 变更可能将使以前有效的工具调用变成错误请求，或导致 AI 客户端误解结果。

故障排除

某个操作没有变成工具

检查导入警告、操作的 HTTP 方法和路径、操作是否被选中，以及必需的 schema 引用是否能解析。

工具描述很差或很通用

改进 OpenAPI 的摘要、描述、operationId、参数描述和响应文档。AI 客户端在决定调用哪个能力时依赖这些文本。

调用因认证错误失败

将 OpenAPI 安全方案与运行时提供的凭证进行比较。检查 API 期望的是 bearer header、特定位置的 API key 还是 OAuth 流程。不要通过将凭证放入工具 schema 来解决问题。

服务器暴露了太多工具

减少选中的操作集或将无关的产品区域分离到不同的 MCP 服务器中。大型 API 表面积并不自动成为一个有用的 AI 接口。

响应不可用

检查端点返回的是工作流需要的 JSON 数据。0mcp 目前专注于基于 JSON 的 API 响应；文件上传、文件下载和二进制 API 响应不受支持。

实用的发布检查清单

在分享一个从 API 派生的 MCP 服务器之前，确认：

• OpenAPI 规范有效且使用支持的版本；
• 操作有清晰的名称和描述；
• 只暴露了必要的功能；
• 路径、查询、body 和响应 schema 与真实 API 行为一致；
• 认证已记录在案且凭证在运行时传递；
• 有效和无效的调用都已测试；
• 分页、速率限制和权限已被理解；
• 存在用于未来 API 变更的版本化更新流程。

OpenAPI 规范本身不是一个 MCP 服务器。当契约准确且暴露的能力表面是有意为之的时候，它才是构建 MCP 服务器的强力来源。

如果你想采用托管路线，探索 0mcp API-to-MCP 工作流，或遵循 OpenAPI-to-MCP 文档来审查实现路径。