OpenAPI to MCP Configuration

Configuration reference for the OpenAPI to MCP plugin (`openapi-to-mcp`): the static configurations and parameters, each attribute with its type, whether it is required, its default and its accepted values.

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:

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 (opens in Apache APISIX docs) for configuration options available to all plugins.

transport — string · optional · default: sse · since API7 Gateway 3.8.15

Valid values: 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 · since API7 Gateway 3.8.13

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.

The OpenAPI-to-MCP service caches the document by this URL string for 3600 seconds by default. To pick up a changed document immediately, change the URL (for example, a query parameter). See OpenAPI Document Caching.

base_url — string · required · since API7 Gateway 3.8.13

Base URL of the API service where requests will be forwarded. Support built-in variables (opens in API7 Gateway docs) in values (available from API7 Enterprise version 3.8.19), for example, https://${http_baseurl}.swagger.io.

allowed_hosts — array[string] · optional · since API7 Gateway 3.9.13

Valid values: 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 · optional · since API7 Gateway 3.8.13

Headers to include in requests to the upstream service. Support built-in variables (opens in API7 Gateway docs) in values, for example, $arg_username-$http_apikey.

flatten_parameters — boolean · optional · default: false · since API7 Gateway 3.8.21

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.