openapi-to-mcp

Serves an HTTP API to MCP clients from its OpenAPI document.

Category AIAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin openapi-to-mcpPriority 540

What it does

openapi-to-mcp turns a route into a Model Context Protocol server for an HTTP API that an OpenAPI document describes. It reads the document at OpenAPI document URL and offers each operation in it to MCP clients as a tool, called at Service base URL when a client uses it.

In the example an MCP client sends tools/list to the route and is answered 200 with a tool named listOrders, the operationId of the document's /orders operation.

When to use it

• The orders API at https://api.example.com publishes openapi.json, and the AI agents of other teams should list and call its operations as tools.
• A partner's agent that should reach your API as MCP tools through the same gateway that already serves the API to its apps.
• A service that expects a header of its own on every call, X-Tenant for example, set once under Headers.

Not for a Model Context Protocol server that runs as a program on the gateway node — see mcp-bridge (Bridges an MCP server's stdio transport over HTTP) or sending prompts to a model and its answer back — see ai-proxy (Proxies requests to an LLM provider with a unified API).

Set it up

Offer an API's operations as MCP tools read from its OpenAPI document

Under Basics set OpenAPI document URL to https://api.example.com/openapi.json and set Service base URL to https://api.example.com. Under Behavior set Transport to streamable_http.

openapi-to-mcp · as the console saves it

{
  "openapi_url": "https://api.example.com/openapi.json",
  "base_url": "https://api.example.com",
  "transport": "streamable_http"
}

Things to know

• OpenAPI document URL — Each operation of the document becomes a tool named by its operationId, so the /orders operation of the example is listed as listOrders.
• Transport — With streamable_http, a client lists the tools with a POST to the route that accepts application/json and text/event-stream.
• Transport — Only sse and streamable_http can be set; grpc is refused when you save.
• OpenAPI document URL — A configuration without the document's address is refused when you save.
• AdvicePut an authentication plugin, key-auth for example, on the same route, so that only your own agents can list and call the API's operations.

Settings

The fields as the console shows them, section by section.

Basics

OpenAPI document URLopenapi_urlstringRequired

Where the OpenAPI document that describes the service is read from.

at least 1 character

Service base URLbase_urlstringRequired

The address the described operations are called at.

at least 1 character

Behavior

Transporttransportstringdefault sse

How the MCP client and this endpoint exchange messages.

one of sse, streamable_http

Headersheadersobject

Headers sent with every call to the service. An object whose keys are a name without a colon, each with a string as its value.

Flatten parametersflatten_parametersbooleandefault false

Puts query and path parameters at the top of each tool input instead of nesting them by kind.

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.