openapi-to-mcp
The openapi-to-mcp plugin enables APISIX to act as a bridge between OpenAPI specifications and MCP (Model Context Protocol) servers. With this plugin, you can expose your existing OpenAPI-based services through an MCP interface, making them accessible to AI models and clients.
The plugin works by converting your OpenAPI specification into the MCP format and serving it through an MCP server interface. Requests from AI clients are then proxied to your upstream services, with support for custom headers and Server-Sent Events (SSE) for real-time streaming responses.
The following diagram illustrates the interaction between the MCP client, APISIX, and an upstream OpenAPI service. The path and data are example values for demonstration.
Examples
The examples below demonstrate how you can configure openapi-to-mcp plugin for different scenarios.
Enable MCP Access to Petstore APIs
The following example demonstrates how to expose the Petstore APIs through the MCP protocol, allowing AI models and clients to interact with the Petstore service.
Create a route with the openapi-to-mcp plugin:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "openapi-to-mcp-route",
"uri": "/mcp",
"methods": ["GET", "POST"],
"plugins": {
"openapi-to-mcp": {
"base_url": "https://petstore.swagger.io/v2",
"headers": {
"Authorization": "special-key"
},
"openapi_url": "https://petstore.swagger.io/v2/swagger.json"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org": 1
}
}
}'
❶ Configure the route to allow GET and POST methods. GET method enables the tool discovery and response streaming (SSE), while POST method enables the execution and action capabilities (messages).
❷ Configure the Petstore API address.
❸ Configure the Petstore API credential.
❹ Configure the Petstore OpenAPI document URL.
❺ Configure any value for the upstream node. The upstream address will not be used for actual request forwarding.
In your AI client, such as Cursor, update the MCP settings with your API7 Enterprise address and append the previously created route path. For instance:
{
"mcpServers": {
"api7-petstore-mcp": {
"url": "http://123.123.123.123:9080/mcp"
}
}
}
If the configuration is successful, you should see the available tools (external functions or services exposed to AI clients through MCP).
You can now interact with API7 Enterprise directly from the chat window of your AI client. For example, try asking: “How many pets are there in the petstore?”
Enable MCP Access to API7 Enterprise APIs
The following example demonstrates how to expose API7 Enterprise APIs through the MCP protocol, enabling AI models and clients to interact with your API7 Enterprise configuration.
Create a route with the openapi-to-mcp plugin:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "openapi-to-mcp-route",
"uri": "/mcp",
"methods": ["GET", "POST"],
"plugins": {
"openapi-to-mcp": {
"base_url": "https://your-dashboard.com",
"headers": {
"X-API-KEY": "a7ee-TVfmSpKpTORtKc0eHc5uCzMI5EfkfCOffWJRgurMcspfTlgGhk-cade674498fe475b81f1e3e1114e508d"
},
"openapi_url": "https://run.api7.ai/api7-ee/openapi-latest.json"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org": 1
}
}
}'
❶ Configure the route to allow GET and POST methods. GET method enables the tool discovery and response streaming (SSE), while POST method enables the execution and action capabilities (messages).
❷ Replace with your API7 Enteprise address, where requests will be forwarded.
❸ Replace with your credential in the X-API-KEY header for API7 Enterprise authentication.
❹ Configure the URL of the API7 Enterprise OpenAPI document.
❺ Configure any value for the upstream node. The upstream address will not be used for actual request forwarding.
In your AI client, such as Cursor, update the MCP settings with your API7 Enterprise address and append the previously created route path. For instance:
{
"mcpServers": {
"api7-enterprise-mcp": {
"url": "http://123.123.123.123:9080/mcp"
}
}
}
If the configuration is successful, you should see the available tools (external functions or services exposed to AI clients through MCP).
You can now interact with API7 Enterprise directly from the chat window of your AI client. For example, try asking: “How many gateway groups are there in API7 Enterprise?”
Configure Authentication for MCP Routes
The following example demonstrates how to expose API7 Enterprise APIs through the MCP protocol when the APISIX MCP route is protected by an authentication method such as key-auth.
Create a consumer johndoe:
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"username": "johndoe"
}'
Configure the key-auth credential for johndoe:
curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "cred-john-key-auth",
"plugins": {
"key-auth": {
"key": "john-key"
}
}
}'
Create a route with the openapi-to-mcp and key-auth plugins:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "openapi-to-mcp-route",
"uri": "/mcp",
"methods": ["GET", "POST"],
"plugins": {
"openapi-to-mcp": {
"base_url": "https://your-dashboard.com",
"headers": {
"X-API-KEY": "a7ee-TVfmSpKpTORtKc0eHc5uCzMI5EfkfCOffWJRgurMcspfTlgGhk-cade674498fe475b81f1e3e1114e508d"
},
"openapi_url": "https://run.api7.ai/api7-ee/openapi-latest.json"
},
"key-auth": {
"header": "apikey"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org": 1
}
}
}'
When an MCP server requires authentication, you can specify headers in the mcp.json configuration. Refer to the documentation of your AI client to verify whether headers are supported.
If Headers Are Supported
For example, in Cursor you can update the MCP settings with your API7 Enterprise address, append the previously created route path, and include the header required for key-auth:
{
"mcpServers": {
"api7-enterprise-mcp": {
"url": "http://123.123.123.123:9080/mcp",
"headers": {
"apikey": "john-key"
}
}
}
}
The configured headers will be added to both GET and POST requests.
If the configuration is successful, you should see the available tools (external functions or services exposed to AI clients through MCP). You can then interact with API7 Enterprise directly from the chat window of your AI client.
If the authentication header is not configured in mcp.json, the AI client will be unable to load tools from the MCP server.
If Headers Are Not Supported
If your AI client does not support configuring headers in mcp.json, you can include the authentication credential in the MCP URL query, since key-auth supports obtaining credential from the URL query.
Update the key-auth configuration on the route as such:
curl "http://127.0.0.1:9180/apisix/admin/routes/openapi-to-mcp-route" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"plugins": {
"key-auth": {
"_meta": {
"filter": [
[
"request_method",
"==",
"GET"
]
]
},
"query": "apikey"
}
}
}'
❶ Only apply the key-auth on GET requests. This is because the apikey configured in the query parameter is only sent with the GET request to the SSE endpoint. It is not included in the subsequent POST message requests. As a result, the message requests will be blocked by the key-auth plugin if the filter is not applied.
❷ Configure the plugin to obtain the authentication key from the query.
In your AI client, include the credential in the MCP server address query:
{
"mcpServers": {
"api7-enterprise-mcp": {
"url": "http://123.123.123.123:9080/mcp?apikey=john-key"
}
}
}
If the configuration is successful, you should see the available tools (external functions or services exposed to AI clients through MCP). You can then interact with API7 Enterprise directly from the chat window of your AI client.
If the authentication credential is not configured in the MCP server URL query, the AI client will be unable to load tools from the MCP server.