将 REST API 暴露为 AI Agent 的 MCP 工具
openapi-to-mcp 插件将现有 REST API 暴露为 AI Agent 可通过 MCP(模型上下文协议)发现和调用的工具。现有 API 无需修改,其 OpenAPI 3.x 文档可直接提供工具定义,无需定制 Agent 集成。
该插件将 MCP 流量转发到与网关一同部署的 OpenAPI-to-MCP 服务。该服务将每个 OpenAPI 操作发布为工具,并把工具调用转换为上游 HTTP 请求。
MCP 网关的工作原理
请求路径如下:
AI Agent(AI 智能体)-> MCP 客户端 -> API7 网关 -> OpenAPI-to-MCP 服务 -> 上游 REST API
该插件不会启动 MCP 服务器,而是将请求代理到单独部署的 OpenAPI-to-MCP 服务,默认地址为 127.0.0.1:3000。该服务必须与网关共享网络命名空间,并提供两种传输模式:
sse(默认):- 通过
GET /.api7_mcp/sse获取事件流 - 向 MCP 消息端点发送
POST消息
- 通过
streamable_http:- 无状态
POST /.api7_mcp/mcp_stateless
- 无状态
对于 SSE 连接请求和 Streamable HTTP 请求,插件都会在将请求转发到 MCP 边车之前,根据插件配置自动注入 x-openapi2mcp-base-url 和 x-openapi2mcp-openapi-spec 请求头,无需手动设置。
前置条件
开始前,请确保具备:
-
正在运行的 API7 Enterprise 网关(
openapi-to-mcp仅企业版提供)。 -
将 OpenAPI-to-MCP 服务部署在与网关相同的网络命名空间中。如果使用 Helm 部署,设置
openapiToMcp.enabled: true。如果使用 Docker 或裸机部署,请参阅准备 API7 网关。 -
从控制台获取 Token,并保存到环境变量:
export API_KEY=your-dashboard-token # 请替换为你的控制台 Token -
将
{gateway_group_id}替换为网关组 ID。如果正在按照快速入门操作,请使用default。 -
如果使用 Admin API 示例,请在 API7 网关中创建或复用一个服务。如果尚无服务,请按照创建或复用服务操作,然后将服务 ID 保存到环境变量中:
export SERVICE_ID=your-service-id # 请替换为你的服务 ID -
按照
openapi-to-mcp→ 启动 Petstore 启动固定版本的 Petstore 示例服务。对于 Kubernetes 部署,将示例命名空间aic替换为网关所在的命名空间(通常为api7)。此示例服务随后会从网关网络的http://petstore:8080提供 OpenAPI 文档和 API。 -
用于验证的 MCP 客户端,例如 Claude Desktop 或其他 MCP 兼容客户端。
配置 MCP 网关
配置一个将固定版本 Petstore 示例服务暴露为 MCP 工具的路由。该示例服务同时提供 OpenAPI 文档和生成的工具所使用的 API。
- Admin API
- ADC
curl -k "https://localhost:7443/apisix/admin/routes/openapi-to-mcp-route?gateway_group_id={gateway_group_id}" -X PUT \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
--data-binary @- <<EOF
{
"name": "openapi-to-mcp-route",
"service_id": "$SERVICE_ID",
"paths": ["/.api7_mcp/*"],
"plugins": {
"openapi-to-mcp": {
"openapi_url": "http://petstore:8080/api/v3/openapi.json",
"base_url": "http://petstore:8080/api/v3",
"transport": "sse",
"headers": {},
"flatten_parameters": false
}
}
}
EOF
❶ openapi_url 指向 OpenAPI 3.x 文档。OpenAPI-to-MCP 服务解析此规范,并根据其中的操作构建 MCP 工具。
❷ base_url 是调用工具时使用的上游 REST API 基础地址。
❸ transport 选择 MCP 传输方式,可使用 sse(默认)或 streamable_http。
❹ flatten_parameters 用于控制生成工具输入 Schema 时是否展平嵌套参数。
services:
- name: MCP Gateway
labels:
docs-example: openapi-to-mcp-guide
routes:
- uris:
- /.api7_mcp/*
name: openapi-to-mcp-route
plugins:
openapi-to-mcp:
openapi_url: http://petstore:8080/api/v3/openapi.json
base_url: http://petstore:8080/api/v3
transport: sse
headers: {}
flatten_parameters: false
❶ openapi_url 指向 OpenAPI 3.x 文档。OpenAPI-to-MCP 服务解析此规范,并根据其中的操作构建 MCP 工具。
❷ base_url 是调用工具时使用的上游 REST API 基础地址。
❸ transport 选择 MCP 传输方式,可使用 sse(默认)或 streamable_http。
❹ flatten_parameters 用于控制生成工具输入 Schema 时是否展平嵌套参数。
预览示例服务的配置,并确认差异中没有意外的更新或删除:
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=openapi-to-mcp-guide
同步已审查的服务配置:
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=openapi-to-mcp-guide