> ## Documentation Index > Fetch the complete documentation index at: https://neuraltrust-92b43583-develop.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/neuraltrust/deployment/hybrid) so the data plane runs where they are reachable. ## Add your API Go to **TrustGate → Registry → MCP → Add custom**, and set **Source** to **OpenAPI document**. 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. See [Connecting to your API](#connecting-to-your-api) below. Select **Validate OpenAPI**. TrustGate downloads the document and previews the tools it would create. The registry cannot be connected until validation succeeds. Save, then bind the server to an [MCP consumer](/trustgate/mcp/overview) 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). ## 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 `. 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](/trustgate/mcp/overview): consumers, toolkits, and upstream authentication * [Registries](/trustgate/concepts/registries): connect MCP and LLM backends * [Connect from Cursor](/integrations/cursor)