Docs
Plugin HubConfiguration Options

Static Configurations

In API7 Enterprise, the plugin proxies MCP traffic to the OpenAPI-to-MCP service at 127.0.0.1:3000 by default. These static settings apply only to that sidecar deployment. APISIX handles MCP inside the gateway and needs no sidecar port configuration.

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.

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

    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.

    Streamable HTTP was introduced in API7 Enterprise 3.8.15 and APISIX 3.19.0. SSE deployments with multiple gateway instances require session affinity.

  • openapi_url

    string

    required

    URL of the OpenAPI specification document that defines the API structure to be exposed through MCP.

    APISIX accepts OpenAPI 3.x documents in JSON or YAML and resolves internal references and absolute HTTP or HTTPS references. Swagger 2.0 support is best effort and does not convert body or form-data parameters into tool inputs.

    The Enterprise OpenAPI-to-MCP service supports OpenAPI 3, not Swagger 2. It has a known parsing issue with oneOf schemas that can leave the client stuck loading tools.

    Generated tools are cached by this URL. Change the URL, for example with a version query parameter, to load a changed document immediately. See OpenAPI Document Caching.

  • base_url

    string

    required

    Base URL of the API service where requests will be forwarded. Built-in variable support was introduced in API7 Enterprise 3.8.19 and APISIX 3.19.0; see the variable references for API7 Gateway (opens in API7 Gateway docs) and APISIX (opens in Apache APISIX docs). Keep this URL operator-controlled in APISIX, which does not implement the Enterprise allowed_hosts restriction.

  • 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. Introduced in API7 Enterprise 3.9.13. Not available in APISIX 3.19.0.

  • headers

    object

    Headers to include in requests to the upstream service. Values can use API7 Gateway variables (opens in API7 Gateway docs) or APISIX variables (opens in Apache APISIX docs), such as $http_x_api_key. APISIX resolves values once per SSE session and for every Streamable HTTP request. Native APISIX does not automatically forward the Enterprise sidecar's x-openapi2mcp-header-* client headers.

  • flatten_parameters

    boolean

    default: false

    Whether to flatten parameters in the tool schema. Query and path parameter flattening was introduced in API7 Enterprise 3.8.21, and header parameter support in 3.9.8. All three parameter locations are supported in APISIX 3.19.0.

    If set to false, query, path, and header parameters are nested under queryParameters, pathParameters, and headerParameters. If set to true, they are placed directly under properties.

    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.

  • cache_enabled

    boolean

    default: true

    Whether the OpenAPI-to-MCP service caches the OpenAPI document of this route and the tools generated from it. If set to false, the service downloads and parses the document again every time it loads the tools, which suits a document that is still changing.

    Requires the api7/openapi-to-mcp sidecar version 1.0.5 or later. An earlier sidecar ignores this option and applies its own CACHE_ENABLED setting.

    Introduced in API7 Enterprise 3.9.21. Not available in API7 Enterprise 3.10.7 or APISIX 3.19.0.

  • cache_ttl

    integer

    default: 3600

    vaild vaule:

    greater than or equal to 1

    Seconds that the OpenAPI document of this route and the tools generated from it stay in the cache of the OpenAPI-to-MCP service.

    Requires the api7/openapi-to-mcp sidecar version 1.0.5 or later. An earlier sidecar ignores this option and applies its own CACHE_TTL setting.

    Introduced in API7 Enterprise 3.9.21. Not available in API7 Enterprise 3.10.7 or APISIX 3.19.0.

Overview

Previous Page