跳到主要内容
版本:3.9.x

将 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。

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 时是否展平嵌套参数。

使用 MCP 客户端验证​

第 1 步:连接并发现工具​

SSE 模式​

将 MCP 客户端连接到 SSE 端点:

curl -N "http://127.0.0.1:9080/.api7_mcp/sse"

连接成功后会返回事件流,其中包含会话专用端点:

event: endpoint
data: /.api7_mcp/sse?sessionId=abc123xyz

sessionId 值标识由 MCP 边车创建的 SSE 会话。请使用事件流返回的会话专用端点,而不是网关上配置的路由模式。

Streamable HTTP 模式​

同一路由上的两种传输模式互斥。在使用以下 Streamable HTTP 示例之前,请先将前文路由配置中的 transport 从 sse 改为 streamable_http,再通过 Admin API 或 adc sync 重新应用配置。

发送 tools/list 请求以发现可用工具:

curl -s "http://127.0.0.1:9080/.api7_mcp/mcp_stateless" \
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}'

响应应为 SSE message 事件,其工具列表包含类似以下的条目:

{
"name": "getPetById",
"description": "Returns a single pet"
}

第 2 步:调用工具​

确保路由已配置为 streamable_http 后,调用工具以验证端到端 REST 转发。以下示例调用需要路径参数 petId 的 getPetById。由于 flatten_parameters 为 false,请将该参数放在 pathParameters 下。

curl -s "http://127.0.0.1:9080/.api7_mcp/mcp_stateless" \
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "getPetById",
"arguments": {
"pathParameters": {
"petId": 1
}
}
}
}'

调用成功后会返回 HTTP 200,MCP 结果中包含 ID 为 1 的 Petstore 资源。根据已部署的 OpenAPI-to-MCP 服务版本,资源可能位于 JSON 编码的上游响应封装中,也可能直接出现在结果中,包括作为 structuredContent 返回。

安全注意事项​

将 API 暴露为 MCP 工具时,应实施与生产 API 流量相同的控制:

  • 身份认证:在 MCP 工具调用到达 OpenAPI-to-MCP 服务之前,强制执行网关身份认证(API Key、JWT、mTLS)。
  • 授权:限制 Agent 身份可以访问的路由和操作。
  • 限流:应用基于请求或 Token 的限制,防止滥用或失控的 Agent 流量。
  • 边车出站流量:限制 OpenAPI-to-MCP 服务的网络出站流量,因为它会获取 OpenAPI 文档并直接发送上游请求。当 base_url 包含变量时,请配置 allowed_hosts。

后续步骤​