OpenAPI to MCP | APISIX & API7 API Gateway Docs

Static Configurations

By default, the plugin proxies MCP traffic to the OpenAPI-to-MCP service at 127.0.0.1:3000.

The file to update depends on how the gateway is deployed:

Host or Docker
Kubernetes (Helm)

For host or Docker deployments, configure the following settings:

config.yaml
plugin_attr:
  openapi-to-mcp:
    port: 4000

Then reload the gateway for static configuration changes to take effect.

For Helm deployments, set the following values in the API7 Gateway Helm chart. Keep the plugin attribute port and the chart-managed sidecar port the same.

values.yaml
openapiToMcp:
  enabled: true
  port: 4000
pluginAttrs:
  openapi-to-mcp:
    port: 4000

Then apply the values file to the existing gateway release:

helm upgrade <gateway-release-name> api7/gateway -n <namespace> -f values.yaml

When changing this value outside Helm, you must also update the OpenAPI-to-MCP service to listen on the same port, otherwise the plugin will fail with a 503.

Parameters

See plugin common configurations for configuration options available to all plugins.

transport
string
default: sse
vaild vaule:
sse or streamable_http
Transport method for client-server communication. The streamable_http method is recommended for production deployments, as it supports stateless communication suitable for multiple gateway instances. The sse method is stateful and may exhibit unexpected behavior when multiple gateways are deployed.
The streamable_http transport is available from API7 Enterprise version 3.8.15.
openapi_url
string
required
URL of the OpenAPI specification document that defines the API structure to be exposed through MCP.
Note that the plugin supports only OpenAPI Specification (OAS) version 3. OpenAPI v2 (Swagger) is not supported.
Additionally, the plugin has a known parsing issue when handling oneOf schemas in OpenAPI v3 document retrieved from openapi_url. In this case, the MCP client will be stuck at tool loading.
base_url
string
required
Base URL of the API service where requests will be forwarded. Support built-in variables in values (available from API7 Enterprise version 3.8.19), for example, https://${http_baseurl}.swagger.io.
allowed_hosts
array[string]
vaild vaule:
Exact host names or wildcard host names such as api.example.com and *.example.com
Optional allow-list of hosts that the resolved base_url may target. When set, requests whose resolved host is not in the list are rejected with HTTP 400. Available in API7 Enterprise from version 3.9.13. Not available in APISIX yet.
headers
object
Headers to include in requests to the upstream service. Support built-in variables in values, for example, $arg_username-$http_apikey.
flatten_parameters
boolean
default: false
Whether to flatten parameters in the tool schema. Flattening of query and path parameters is available from API7 Enterprise version 3.8.21. Support for header parameters defined in the OpenAPI spec (in: header) is available from version 3.9.8. Not available in APISIX yet.
If set to false, query parameters are nested under queryParameters and path parameters are nested under pathParameters. From API7 Enterprise version 3.9.8, header parameters are nested under headerParameters. If set to true, query and path parameters are placed directly under properties, and header parameters are also placed directly under properties from version 3.9.8.
Setting the parameter to true simplifies AI model interaction by reducing schema complexity. Keep the parameter at false when query, path, and header parameters share the same names, to avoid conflicts.

Static Configurations​

Parameters​

Static Configurations

Parameters