OpenAPI 转 MCP：将 REST API 变成安全的 AI 工具

更新时间 8/14/2026

核心要点

  • OpenAPI 转 MCP 让团队无需为每项服务单独构建和运维 MCP Server，就能向 AI 智能体开放现有 REST API。
  • AISIX AI Gateway 从 OpenAPI 3.x 操作生成带命名空间的 MCP 工具，并通过同一个 MCP 端点，将这些工具与上游 MCP Server 的工具统一呈现。
  • 网关将调用方凭证与上游 REST API 凭证分离，因此智能体无法获得后端密钥。
  • 生成的工具可以使用 AISIX 中其他 MCP 工具同样的访问控制、限流、防护规则与可观测性链路。
  • 转换存在明确边界：支持常见 HTTP 操作和 JSON 请求体，但不会将 Swagger 2.0 或 multipart 上传转换为工具。
  • 生产发布应从少量经过审核的操作开始，只授予精确工具名，并同时验证允许和拒绝的调用。

对多数企业而言，OpenAPI 转 MCP 的最大价值，在于 AI 智能体建设并非始于一张空白的基础设施图。企业通常已经通过 REST API 沉淀了多年的业务能力，包括库存查询、支持工单、支付状态、部署操作、员工目录和内部搜索。让智能体安全、以机器可读方式使用这些能力，往往比重建所有系统更快产生价值。

模型上下文协议（MCP）提供了这种接口。MCP 客户端可以通过标准协议发现工具、查看输入 Schema 并调用工具。真正的难点，是如何把庞大的 API 资产转化为工具入口，同时避免为每个 API 再创建一个应用、把凭证复制到智能体运行环境，或者绕过既有的运维控制。

AISIX AI Gateway 可以将 OpenAPI 3.x 文档作为 MCP Server 来源。它基于受支持的 API 操作生成工具，将工具调用转换为 HTTP 请求，并确保认证、授权、流量控制、内容检查和遥测始终位于网关链路中。

为什么为每个 API 重建 MCP Server 难以扩展

如果需要加入后端 API 本身不具备的编排、状态或领域逻辑，专门构建 MCP Server 是合理的选择。但如果只是为了包装一个已有清晰描述的 REST 端点而创建 MCP Server，团队就需要额外开发、保护、部署、版本化和监控第二套集成面。

假设某个组织希望运维智能体使用三项现有服务：

  • 通过 SKU 查询库存的库存 API；
  • 创建和读取事件的工单 API；
  • 报告发布状态的部署 API。

智能体需要工具名称、说明和输入 Schema，而不需要三套新的业务实现。OpenAPI 已经描述了操作、参数和 JSON 请求体。OpenAPI 转 MCP 层可以将这些契约转换为工具，同时保持底层 API 不变。

1flowchart LR
2    Specs["OpenAPI 3.x 文档"] --> Gateway["AISIX AI Gateway"]
3    Servers["上游 MCP Server"] --> Gateway
4    Gateway --> Endpoint["聚合的 /mcp 端点"]
5    Endpoint --> Agent["MCP 客户端或 AI 智能体"]
6    Gateway --> Inventory["库存 REST API"]
7    Gateway --> Tickets["工单 REST API"]
8    Gateway --> Deployments["部署 REST API"]

这种分层带来了更清晰的职责模型。API 团队继续负责业务行为和 OpenAPI 契约；平台团队负责网关、凭证和策略；智能体团队消费稳定的 MCP 工具入口，而不必在每个应用中编写协议适配与密钥处理逻辑。

它还能减少治理漂移。生成工具不会产生绕过网关的直连路径，调用仍然受平台和安全团队为 MCP 流量设置的控制措施约束。

AISIX 如何将 OpenAPI 转换为 MCP 工具

在 AISIX 中，MCP Server 注册项可以使用 type: openapi 并指向 REST API 基础 URL。工具定义来自其 OpenAPI 3.x 文档。AISIX 遍历文档的 paths，为每个受支持的 get、post、put、delete 或 patch 操作生成一个工具。

工具命名是确定性的。如果操作包含 operationId，AISIX 会将其转换为小写、替换不受支持的字符，并将结果限制在 128 个字符以内。如果没有 operationId，网关会根据 HTTP 方法和路径生成名称，随后再添加已注册 Server 名称作为命名空间。例如，一个名为 getItem 的操作位于 erp Server 上时，聚合端点会将其公开为 erp__getitem。

以下是一个最小化的 OpenAPI 文档：

1openapi: 3.0.3
2info:
3  title: ERP Inventory API
4  version: 1.0.0
5paths:
6  /items/{id}:
7    get:
8      operationId: getItem
9      summary: Get an inventory item by ID
10      parameters:
11        - name: id
12          in: path
13          required: true
14          schema:
15            type: string
16      responses:
17        "200":
18          description: Inventory item found

AISIX 将路径参数转换为必填工具输入，并将该操作公开为 erp__getitem。路径和查询参数会保留类型、说明、枚举值及是否必填等有用的 Schema 信息。JSON 请求体会转换为 body 对象。本地 $ref 会被解析，因此 MCP 客户端收到的是实际引用的 Schema，而不是尚未解析的指针。

转换会有意排除应由网关控制的字段。请求头和 Cookie 参数不会作为由智能体提供的工具参数暴露，因为它们经常携带凭证、租户路由或其他基础设施上下文，应由可信策略设置，而不是交给模型生成。

转换也有一些实际限制：

  • 文档必须采用 OpenAPI 3.x，Swagger 2.0 会被拒绝。
  • 如果某个操作没有 application/json 请求体变体，AISIX 会跳过它。例如，multipart 文件上传不会生成工具。
  • AISIX Cloud 会拒绝无法解析、不包含可用操作，或者 operationId 规范化后发生冲突的文档。
  • 对于开源版资源文件，系统会验证资源结构，而网关会在客户端列出或调用工具时生成工具。名称冲突会添加数字后缀，因此团队应在发布前检查最终工具列表。

这些限制也是有用的设计信号。API 在技术上可访问，并不意味着其中每项操作都适合作为智能体工具。文件上传、非常规编码的请求体和权限宽泛的管理端点，往往更适合专门设计的工作流，而不是自动公开。

当一个 API 操作已经对应一个清晰的业务动作时，可以直接转换。如果工具需要协调多个 API、保存会话状态、等待人工审批，或者把不稳定的后端响应重塑为持久契约，则应构建专用 MCP Server。明确这条边界，可以避免协议复用在无意间变成工作流设计。

应将 OpenAPI 文档视为受治理的发布制品，而不是实时发现的捷径。在 AISIX Cloud 中，spec_url 会在注册期间被获取并存储；数据面不会反复获取它，因此外部文档的变化不会静默修改工具目录。如果控制面无法访问私有规范，可以使用 spec_content，同时需要注意 Cloud 文档大小上限为 1 MiB。在开源部署中，变更通过经过审核的 resources.yaml 重载进入系统。无论采用哪种方式，都应对文档进行版本管理，在发布前比较生成的工具名，并且只在充分了解新的工具入口后更新调用方授权。

将 API 凭证和目标地址置于网关控制之下

OpenAPI 转换只解决接口问题。生产设计还必须明确谁可以调用生成的工具，以及网关如何向后端 API 认证。这是两条独立的信任边界。

MCP 客户端向网关发送 AISIX 调用方 API key。AISIX 使用该 key 验证调用方身份，并计算其有效工具授权。随后，网关在调用 REST API 时使用为 OpenAPI Server 配置的凭证。调用方 key 不会作为上游凭证转发，后端凭证也不会返回给客户端。

AISIX 支持四种上游认证模式：

  • none：服务不要求网关凭证；
  • bearer：静态 Bearer Token；
  • api_key：通过 x-api-key 发送 key；对于 OpenAPI Server，也可以通过 api_key_header 选择自定义请求头；
  • oauth2：采用客户端凭证授权流程，并缓存访问令牌。

平台团队因此可以在一个位置轮换或撤销后端凭证，而无需修改智能体配置。某项上游凭证失效只会使对应 Server 的工具不可用，不会暴露密钥，也不会阻止其他 MCP Server 继续运行。

执行生成工具时，AISIX 还会实施目标地址保护。它不会跟随重定向，从而防止凭证被重新发送到意外主机。对于路径参数，它会拒绝包含 / 或 \ 的值，也会拒绝 . 和 ..，避免调用方利用生成的路径字段逃逸出配置的操作路径。

最终的请求流程会明确区分身份与凭证：

1sequenceDiagram
2    participant Client as MCP 客户端
3    participant AISIX as AISIX AI Gateway
4    participant Policy as 访问与安全控制
5    participant API as REST API
6
7    Client->>AISIX: tools/call erp__getitem + 调用方 API key
8    AISIX->>Policy: 授权工具并检查限制
9    Policy-->>AISIX: 允许
10    AISIX->>Policy: 检查工具参数
11    Policy-->>AISIX: 通过
12    AISIX->>API: GET /items/42 + 网关持有的凭证
13    API-->>AISIX: JSON 响应
14    AISIX->>Policy: 检查文本结果
15    Policy-->>AISIX: 通过
16    AISIX-->>Client: MCP 工具结果

该设计不会因为智能体持有有效 key 就默认其可信。系统会验证调用方身份、授权特定工具、约束流量，并在后端调用前后检查内容。

从生成工具走向生产可用工具

AISIX Cloud 可以通过 Admin API 注册基于 OpenAPI 的 Server。下面的示例将密钥保存在环境变量中，并向一个环境开放 ERP API：

1export AISIX_CP="http://localhost:8080/api"
2export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
3export ENV_ID="YOUR_ENVIRONMENT_ID"
4export ERP_API_TOKEN="YOUR_ERP_SERVICE_TOKEN"
5
6curl -fsS -X POST "$AISIX_CP/mcp_servers" \
7  -H "Authorization: Bearer $AISIX_TOKEN" \
8  -H "Content-Type: application/json" \
9  --data-binary @- <<EOF
10{
11  "name": "erp",
12  "type": "openapi",
13  "url": "https://erp.internal/api/v1",
14  "spec_content": "{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"ERP\",\"version\":\"1.0.0\"},\"paths\":{\"/items/{id}\":{\"get\":{\"operationId\":\"getItem\",\"parameters\":[{\"name\":\"id\",\"in\":\"path\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"description\":\"OK\"}}}}}}",
15  "auth_type": "bearer",
16  "secret": "$ERP_API_TOKEN",
17  "allowed_environments": ["$ENV_ID"]
18}
19EOF

注册后，应查看响应中的 tool_names，或调用 Server 的工具端点。然后向调用方授予最小范围的实际名称，例如 erp__getitem。如果智能体只需要一个读取操作，就不要授予 erp__*。

开源 AISIX 网关通过 resources.yaml 提供相同的运行时行为：

1_format_version: "1"
2
3api_keys:
4  - display_name: inventory-agent
5    key_env: INVENTORY_AGENT_KEY
6    allowed_models: []
7    allowed_tools:
8      - erp__getitem
9
10mcp_servers:
11  - name: erp
12    type: openapi
13    url: https://erp.internal/api/v1
14    auth_type: bearer
15    secret: ${ERP_API_TOKEN}
16    spec:
17      openapi: 3.0.3
18      info:
19        title: ERP Inventory API
20        version: 1.0.0
21      paths:
22        /items/{id}:
23          get:
24            operationId: getItem
25            parameters:
26              - name: id
27                in: path
28                required: true
29                schema:
30                  type: string
31            responses:
32              "200":
33                description: Inventory item found

重载网关前，应验证完整的资源文件。随后测试三项行为：允许的工具出现在 tools/list 中；允许的调用可以到达 ERP API；另一个生成工具会被隐藏，并在路由到上游前被拒绝。

工具生成只是生产流程的起点，而不是终点。在 AISIX Cloud 中，团队可以要求 Server 在发布前经过审核与批准，再通过共享的 MCP 访问策略控制环境和团队访问。Cloud 和开源部署都可以应用按 key 的工具授权、请求与并发限制、防护规则以及遥测。预算、共享策略和 Server 审核工作流属于 AISIX Cloud 功能。

OpenAPI 转 MCP 常见问题

AISIX 可以把任何 API 转换为 MCP 工具吗？

AISIX 会根据 OpenAPI 3.x 文档中受支持的操作生成工具。来源必须是由 OpenAPI 描述的 REST API；请求体格式不受支持的操作不会自动转换。应检查生成的工具列表，而不是假设每条路径都已经可以调用。

MCP 客户端会获得 REST API 凭证吗？

不会。客户端使用调用方 API key 向 AISIX 认证。AISIX 会在上游请求中单独附加已配置的 Bearer Token、API key 或 OAuth2 客户端凭证令牌。后端凭证始终保留在网关侧。

OpenAPI 转 MCP 支持 Swagger 2.0 或 multipart 上传吗？

这一 AISIX 工作流不接受 Swagger 2.0 文档。如果操作没有 application/json 请求体变体，包括 multipart 文件上传，AISIX 会跳过该操作，而不是把无法正确执行的操作公开为工具。

在不失去控制的前提下让现有 API 服务智能体

OpenAPI 转 MCP 的价值，在于复用企业已经信任的两类资产：REST API 实现及其机器可读契约。AISIX 补齐了协议与治理层。智能体获得名称与 Schema 可预测的工具，平台团队则继续掌控凭证、授权、流量、内容检查和遥测。

可以先从一个只读 API 和一项精确工具授权开始。验证生成的 Schema，测试允许与拒绝的调用，并观察相应的用量事件。确认这条链路后，再实施最小权限 MCP 访问控制，然后扩展工具目录。

参阅完整的将 REST API 公开为 MCP 工具指南，注册 OpenAPI 文档，并通过 AISIX AI Gateway 调用第一个生成工具。

获取方案