将 REST API 暴露为 MCP 工具

本文介绍如何使用 openapi-to-mcp 插件将现有 REST API 暴露为 MCP 工具。API7 Gateway 读取 OpenAPI 定义，启动本地 MCP 服务器，并把每个接口操作映射为 AI 智能体可发现和调用的工具。

场景概述

MCP（Model Context Protocol）是一种连接 AI 智能体和外部工具的开放协议。没有 MCP 时，智能体对接 REST API 通常需要定制开发，且维护成本较高。openapi-to-mcp 插件可以在网关层将 OpenAPI 3.x 操作转换为 MCP 工具定义。

这种方式带来的好处包括：

• 现有 REST API 无需改造。
• AI 智能体可以通过 MCP 动态发现工具。
• 工具调用最终会被转换为普通上游 HTTP 请求，并继续经过 API7 Gateway 治理。

MCP 网关工作方式

请求路径如下：

AI 智能体 → MCP 客户端 → API7 Gateway（MCP Server）→ 上游 REST API

插件运行时会启动本地 MCP 服务器，并支持两种传输模式：

• sse（默认）：
  • GET /.api7_mcp/sse 用于事件流。
  • MCP 消息端点使用 POST 请求。
• streamable_http：
  • 无状态 POST /.api7_mcp/mcp_stateless。

在 streamable_http 无状态模式下，每个 MCP 请求都需要带上以下请求头：

Header	用途	示例
x-openapi2mcp-base-url	REST 调用的基础 URL	https://petstore3.swagger.io
x-openapi2mcp-openapi-spec	OpenAPI 规格地址	https://petstore3.swagger.io/api/v3/openapi.json
Accept	需要包含 SSE 支持	application/json, text/event-stream

前提条件

• 已有 API7 企业版网关环境，openapi-to-mcp 是企业版插件。
• 上游服务提供有效的 OpenAPI 3.x 规格。
• 准备 MCP 客户端，例如 Claude Desktop 或其他兼容 MCP 的客户端。

配置 MCP 网关

以下示例使用必要的基础配置：

{
  "openapi_url": "http://upstream/openapi.json",
  "base_url": "http://upstream:8080",
  "transport_mode": "sse",
  "headers": {},
  "flatten_parameters": false
}

Admin API

curl "http://127.0.0.1:7080/apisix/admin/routes?gateway_group_id=default" -X PUT \
  -H "X-API-KEY: $ADMIN_API_KEY" \
  -d '{
  "id": "openapi-to-mcp",
  "service_id": "'"$SERVICE_ID"'",
  "paths": ["/.api7_mcp/*"],
  "plugins": {
    "openapi-to-mcp": {
      "openapi_url": "http://upstream/openapi.json",
      "base_url": "http://upstream:8080",
      "transport_mode": "sse",
      "headers": {},
      "flatten_parameters": false
    }
  }
}'

ADC

adc.yaml

services:
  - name: MCP Gateway Service
    routes:
      - name: openapi-to-mcp
        uris:
          - /.api7_mcp/*
        plugins:
          openapi-to-mcp:
            openapi_url: http://upstream/openapi.json
            base_url: http://upstream:8080
            transport_mode: sse
            headers: {}
            flatten_parameters: false

安全建议

• 不要把所有内部 API 无差别暴露给 AI 智能体，应结合路由、消费者和访问控制限制可调用范围。
• 对敏感操作增加审批、幂等保护和审计日志。
• 对工具调用设置限流，避免智能体循环调用导致系统压力升高。
• 对 OpenAPI 描述进行人工审核，确保工具名称和参数说明准确、可控。