OpenAPI to MCP

Generate MCP tools from an OpenAPI 3 document and connect them through TrustGate

If your API publishes an OpenAPI 3 document, TrustGate can expose its supported operations as tools. You do not have to build or run an MCP server.

Agents continue to connect to TrustGate. When one calls a tool, TrustGate makes the matching REST request to your API and returns the response.

An OpenAPI backend provides tools only, not prompts or resources. Other MCP servers on the same consumer still contribute theirs.

Before you start

You need two things:

What	Details
The document URL	A link to the raw OpenAPI file (.json or .yaml), version 3. Not the Swagger UI page you read in a browser.
A credential	Whatever your API expects from a service account: an API key, a bearer token, or OAuth client credentials. Skip this if the API is open.

TrustGate has to be able to reach both the document and the API itself. If they live on a private network, use Hybrid so the data plane runs where they are reachable.

Add your API

1. Start a custom server

   Go to TrustGate → Registry → MCP → Add custom, and set Source to OpenAPI document.

2. Paste the document URL

   Put the link to your OpenAPI file in OpenAPI spec URL.

   Leave API base URL empty. TrustGate reads the address of your API from the document. Fill it in only when the document omits the API address or when you need to override it, for example to replace a public URL with an internal one.

3. Choose how TrustGate signs in to your API

   See Connecting to your API below.

4. Validate

   Select Validate OpenAPI. TrustGate downloads the document and previews the tools it would create. The registry cannot be connected until validation succeeds.

5. Connect

   Save, then bind the server to an MCP consumer like any other. Use a toolkit to choose which operations that consumer may actually use.

Reading the validation result

A successful validation shows the number of tools, your API’s title, the address requests will go to, and one line per tool: the method, the path, and the name your agents will see.

It may also show a warning count you can expand. Warnings do not prevent validation. They identify incomplete or potentially unwieldy definitions:

Warning	What it means
N operations without operationId	The document does not name its operations, so TrustGate derives names from each method and path (GET /v1/models-catalog becomes get_v1_models_catalog). Generated names may be less descriptive than explicit operationId values.
N operations skipped	Those operations cannot become tools, usually because they use file uploads or another non-JSON format. Other operations remain available.
This document exposes N tools	The document defines more than 80 tools. Use a toolkit on the consumer to limit the exposed set.

Tool names are the first thing a model reads when deciding what to call. If you own the API, give each operation an operationId in the document. That value becomes the tool name, and listModels guides a model far better than get_v1_models_catalog.

Connecting to your API

This is how TrustGate signs in to your REST API. It is separate from how your agents sign in to TrustGate, which is set on the consumer.

Option	Use it when
None	The API is open to whoever can reach it on the network.
Static header	The API takes a fixed credential: an API key header, or Authorization: Bearer ….
OAuth2 client credentials	The API takes a token you fetch from a token endpoint with a client ID and secret.

TrustGate uses one service credential for every call, so your API sees the gateway, not the individual end user. Per-user sign-in to your API is not part of this integration; see What it does not do.

What it does not do

OpenAPI conversion has the following limitations.

Only OpenAPI 3. Swagger 2.0 documents are rejected: convert one first (with a tool such as swagger2openapi) and publish the result. If your API serves Swagger UI at /docs, that page is not the document. Use the raw file behind it.

No per-user login to your API. TrustGate authenticates with one service credential, so your API cannot tell which person is behind a call. When you need each user to authorize individually, use a real MCP server with forwarded OAuth instead of an OpenAPI backend.

Lists come back one page at a time. If an operation takes page, cursor, or limit, those become tool arguments and the agent asks for the next page itself. TrustGate never walks a whole collection on its own. One tool call is one HTTP request. If an agent needs the complete collection in one call, add an endpoint that returns it.

JSON only. Operations that send file uploads, form posts, or XML are skipped with a warning; the rest of the document still compiles. The same applies to a document that splits itself across several files: TrustGate does not follow references to other URLs, so publish it as a single file.

Size limits. The document may be up to 5 MB and 500 operations, and a single tool response up to 10 MB. Above 80 tools you get a warning, because long tool lists crowd out the model’s context.

Troubleshooting

Validation identifies which phase failed: fetching the document, reading it, or building the tools.

Message mentions	Usually means
fetch	TrustGate could not download the document: wrong URL, the endpoint needs a login, or the host is unreachable from the data plane.
parse	The downloaded file is not a valid OpenAPI 3 document. Common causes include Swagger 2.0, an HTML page instead of the raw file, or a reference to another file.
compile	The document is valid but yields nothing callable, or the API address in it cannot be used.
no callable operations	Every operation was skipped, typically because none of them accept JSON.

If validation succeeds but later tool calls fail, check the API credential. The tool result includes the upstream status and response body.

Example: the TrustGate Admin API

The TrustGate Admin API can be used as a test target because it publishes an OpenAPI 3 document.

1. Use your Admin address plus /docs/openapi.json as the document URL, for example https://admin.example/docs/openapi.json.
2. Leave API base URL empty.
3. Choose Static header with Authorization and Bearer <your admin token>.
4. Validate. The preview lists health checks, gateway operations, and registry operations. It also warns if the document does not name its operations.

Use a restricted toolkit and dedicated token. Do not expose the full Admin API to production agents.

Related

• MCP Gateway: consumers, toolkits, and upstream authentication
• Registries: connect MCP and LLM backends
• Connect from Cursor