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.
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:
| Boundary | Recommended configuration | Why it matters |
|---|---|---|
| Document source | Load openapi_url from a source you control | The document determines which tools and operations are exposed |
| External references | Keep references on the document's origin, or add only the required hosts to allowed_ref_hosts | APISIX otherwise rejects references that use another protocol, host, or port |
| API destination | Keep base_url fixed or derive it from a gateway-controlled variable | A 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
hostorhostsfield. 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.
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, andTransfer-Encoding. - Headers that alter connection behavior:
Connection,Upgrade, andExpect. - 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 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:
| Resource | Behavior at the limit |
|---|---|
| Main and referenced OpenAPI documents | APISIX rejects a document that exceeds its size limit |
| Expanded operation definitions | Remaining references become generic object schemas when expansion reaches the configured complexity limit |
| Tool response bodies | The 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:
| Scope | Behavior |
|---|---|
| Session identity | A 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 headers | APISIX 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 instance | Session state is local to one APISIX instance. Configure session affinity so the stream and message requests reach the same instance |
| Connection capacity | Each stream holds a connection until it closes or reaches its lifetime limit. Apply limit-conn to routes reachable by untrusted clients |
Troubleshoot Rejected Requests
| Symptom | Likely cause | Action |
|---|---|---|
Browser request returns 403 with an origin error | The origin is not allowed, the route has no matching literal host, or the protocol or port differs | Add the trusted origin to allowed_origins, and account for TLS termination and external ports |
| An external reference becomes a generic object | Its target is neither same-origin nor allowed, or it cannot be fetched or parsed | Add only the required host to allowed_ref_hosts, then check APISIX warning logs and connectivity |
| A tool argument or header is not forwarded | The operation does not declare it, the header is protected, or its name or value is invalid | Correct the OpenAPI operation or configure the header on the route |
| A tool call reports an invalid path parameter | The value contains a disallowed separator or creates an empty or dot segment | Keep the value within one path segment, or enable encoded separators only for a compatible upstream |
| Tool discovery returns an error | The document is unreachable, too large, invalid, or has no usable paths object | Check the document URL, response status, format, size, and APISIX error logs |
A tool response reports RESPONSE_TOO_LARGE | The upstream response exceeds the configured response-body limit | Reduce the response or raise the limit after evaluating gateway memory use |
| An SSE message reports that the session was not found | The request reached another instance, route, or consumer, or the session expired | Check session affinity, route selection, authentication, and session lifetime |
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.