Skip to main content

OpenAPI-to-MCP Security and Limits

An OpenAPI-to-MCP route turns an API description into tools and sends tool calls to the described API. This creates two trust boundaries: the document controls what the client sees, and tool arguments influence requests leaving the gateway. Secure both before exposing the route to MCP clients.

Product support

The controls below are available in APISIX 3.20.0. API7 Enterprise 3.9.23 and 3.10.10 process MCP traffic through a separate OpenAPI-to-MCP service. API7 Enterprise can restrict API destinations, but it does not provide the APISIX controls for browser origins, reference hosts, resource limits, or encoded path separators. See the configuration reference for product availability and field definitions.

Trust the Document and API Destination​

The OpenAPI document defines tool names, descriptions, input schemas, and upstream operations. A compromised document can therefore influence the model even when the resulting HTTP request is otherwise valid.

Review each boundary before exposing the route:

BoundaryRecommended configurationWhy it matters
Document sourceLoad openapi_url from a source you controlThe document determines which tools and operations are exposed
External referencesKeep references on the document's origin, or add only the required hosts to allowed_ref_hostsAPISIX otherwise rejects references that use another protocol, host, or port
API destinationKeep base_url fixed or derive it from a gateway-controlled variableA client-controlled value would let the client choose where tool calls are sent

Do not allow document references to internal services or metadata endpoints unless the document requires them. When API7 Enterprise resolves variables in the API destination, use allowed_hosts to restrict the result. APISIX does not provide an equivalent destination allow-list.

Validate Browser Origins​

Browser-based MCP clients send an Origin header. APISIX compares that origin with the route and request to protect browser-accessible MCP routes from DNS-rebinding attacks. This check is not authentication, and requests without an origin are accepted.

When allowed_origins is not configured and the route declares literal hosts, APISIX accepts an origin only when all the following conditions are met:

  • The origin host is a literal value in the route's host or hosts field. A wildcard route host does not establish trust.
  • The origin and the request use the same protocol.
  • The origin and the request use the same port. When the port is omitted, APISIX uses 80 for HTTP or 443 for HTTPS.

If a route has no literal host, APISIX also accepts an origin and request that both use loopback hosts, with matching protocols and ports. Configure allowed_origins when trusted browser origins differ from the route host, including deployments where TLS terminates before APISIX.

caution

List trusted origins explicitly. Allowing every origin removes the DNS-rebinding protection provided by this check.

Constrain Tool Calls​

An MCP client supplies arguments for each tool call. APISIX limits how those arguments can affect the upstream request and preserves the structure of the operation path.

Arguments and Headers​

APISIX forwards only the path, query, and header parameters declared by the matching OpenAPI operation. Undeclared arguments are discarded.

Headers configured on the route take precedence over headers supplied by a tool call, including names that differ only by letter case. APISIX also discards the following:

  • Headers that select the destination or define the request body: Host, Content-Length, and Transfer-Encoding.
  • Headers that alter connection behavior: Connection, Upgrade, and Expect.
  • Invalid header names and values containing a newline.

Configured headers apply to every operation exposed by the document. Expose only operations that may share those credentials. The consumer-restriction plugin can restrict access to the MCP route, but it does not authorize individual tools.

API7 Enterprise header forwarding

API7 Enterprise can forward client headers after removing its OpenAPI-to-MCP prefix. Protect the route with gateway authentication, and configure sensitive upstream credentials in the plugin so that clients cannot override them. See Forward Dynamic Headers with API7 Gateway for the required prefix, precedence, and transport behavior.

Operation Paths​

APISIX prevents path parameters from changing the intended path structure:

  • By default, a path-parameter value containing a slash or backslash is rejected.
  • When encoded path separators are enabled, APISIX percent-encodes them. It still rejects path segments that become empty, . or .. after a separator.
  • A path segment influenced by a parameter cannot resolve to an empty value, . or ...
  • Values inserted into a URI template's query string are encoded as query data.
  • A fragment suffix is removed because URI fragments are not sent in HTTP requests.

Limit Resource Use​

Documents, expanded schemas, and tool responses can consume gateway memory. APISIX bounds each stage independently:

ResourceBehavior at the limit
Main and referenced OpenAPI documentsAPISIX rejects a document that exceeds its size limit
Expanded operation definitionsRemaining references become generic object schemas when expansion reaches the configured complexity limit
Tool response bodiesThe tool call fails with RESPONSE_TOO_LARGE instead of buffering the complete response

Set the limits for the largest trusted documents and API responses the route needs. The configuration reference lists the fields, defaults, and minimum values.

Isolate SSE Sessions​

An SSE connection preserves state across multiple requests, so APISIX stores more session information than it does for Streamable HTTP:

ScopeBehavior
Session identityA session belongs to the route that opened it and to the authenticated consumer, if present. Requests from another route or consumer are rejected
Destination and headersAPISIX determines the API destination and configured headers when the stream opens and reuses them for the session, which can remain in memory for up to 30 minutes. Streamable HTTP determines them for each request
Gateway instanceSession state is local to one APISIX instance. Configure session affinity so the stream and message requests reach the same instance
Connection capacityEach stream holds a connection until it closes or reaches its lifetime limit. Apply limit-conn to routes reachable by untrusted clients

Troubleshoot Rejected Requests​

SymptomLikely causeAction
Browser request returns 403 with an origin errorThe origin is not allowed, the route has no matching literal host, or the protocol or port differsAdd the trusted origin to allowed_origins, and account for TLS termination and external ports
An external reference becomes a generic objectIts target is neither same-origin nor allowed, or it cannot be fetched or parsedAdd only the required host to allowed_ref_hosts, then check APISIX warning logs and connectivity
A tool argument or header is not forwardedThe operation does not declare it, the header is protected, or its name or value is invalidCorrect the OpenAPI operation or configure the header on the route
A tool call reports an invalid path parameterThe value contains a disallowed separator or creates an empty or dot segmentKeep the value within one path segment, or enable encoded separators only for a compatible upstream
Tool discovery returns an errorThe document is unreachable, too large, invalid, or has no usable paths objectCheck the document URL, response status, format, size, and APISIX error logs
A tool response reports RESPONSE_TOO_LARGEThe upstream response exceeds the configured response-body limitReduce the response or raise the limit after evaluating gateway memory use
An SSE message reports that the session was not foundThe request reached another instance, route, or consumer, or the session expiredCheck session affinity, route selection, authentication, and session lifetime
Repeated tool-discovery errors

APISIX caches a failed tool-discovery result for five seconds in the worker process that handled it. Requests that reach the same process during that interval return the cached error without fetching the document or writing the same error log again. After five seconds, the next request retries tool discovery.

For route creation and client requests, see OpenAPI to MCP.