How to turn an OpenAPI spec into an MCP server

An OpenAPI spec already describes the operations and parameters an MCP server needs. Writing the server by hand mostly means copying that into code and keeping the copy in sync as the API changes.

Statio's generator, mcp-gen, does the copying. Give it a spec URL and it writes a TypeScript server on the official MCP SDK, runs it privately, and registers each tool so you can grant them separately.

Prerequisites

• A Statio account. The free plan includes one hosted server generated from a spec.
• An OpenAPI 3.0 or 3.1 spec at a URL Statio can fetch. A spec behind your VPN will not work, so host a copy somewhere reachable.
• The credential your API expects: a bearer token, basic auth or an API key.
• An MCP client such as Claude Code or Cursor, set up as in How to add MCP servers to Claude Code.

Step 1: Check the parts of the spec that become tools

The model only sees what the spec says, so check these first.

• operationId names the tool. In Per Endpoint mode each operation becomes a tool named from its operationId, so getInvoice is the tool the model sees for fetching an invoice. Operations without one get a stable name built from the method and path, which works but reads worse.
• summary is what the model reads. The generator uses the operation's summary as the tool description, falls back to description, and falls back again to the method and path. "Get an invoice by ID, including line items" helps the model pick the right tool, and "GET /v1/invoices/{id}" doesn't.
• servers sets the base URL. Generated tools call the URL in the spec's servers block. You can override it in the next step if the spec points at the wrong environment.
• Parameters should be typed. Path and query parameters are typed from the spec, and references are resolved, including recursive schemas. A bare string with no description leaves the model guessing.

Step 2: Pick a generation mode

The mode decides how many tools the model sees when it connects. That list sits in its context before you ask anything.

Mode	What the model gets	Use it for
Per Endpoint	One tool per operation	Small, focused APIs where the model should see everything up front
Generic	Three tools, whatever the API's size	Large APIs

Generic mode registers three tools ending in list_schemas, get_schema and api_call, each prefixed with a name for your server. The model finds an endpoint, reads its schema, then calls it, and the rest of the API stays on the server until asked for. By our estimate that keeps the tool list around 800 tokens, against tens of thousands for a few hundred endpoints in Per Endpoint mode. Those are estimates, not measurements.

There is also Curated mode, where you name the operations that become direct tools and a fallback reaches everything else. Today it is configured in an mcp-gen.yaml file rather than in the app.

If your spec is large and you want Per Endpoint anyway, the app does not filter endpoints yet. Host a trimmed copy of the spec with only the operations you want, and point Statio at that.

Step 3: Create the server

In the Statio dashboard:

1. Open My MCPs and click Create MCP.
2. Choose Generate from OpenAPI.
3. Fill in a Display Name, a URL-safe Name and a description. The URL-safe name becomes part of the connection URL, so pick something short like billing.
4. Paste the OpenAPI Spec URL and choose a Generation Mode.
5. Click Validate & Preview.

The preview shows counts of endpoints, tools and types, the base URL the tools will call (with Change if it's wrong), the generated tools, and any warnings. Read the tool list. If a name or description looks wrong, fix the spec and validate again. Spec errors are listed with their path in the spec.

When the preview looks right, click Create MCP.

Step 4: Deploy it and let it reach your API

From the server's page, deploy it. Statio fetches the spec, builds an image, deploys it privately on Google Cloud Run and discovers its tools. If a stage fails, the logs say which one.

The server can't do anything useful until you set two things:

• Outbound Access. A server Statio runs has no direct route to the internet. Add your API's host, such as api.example.com, to its outbound allowlist. An empty list means it can reach nothing. Blocked attempts show up in the same panel.
• Credentials. Add the key your API expects. It is encrypted at rest and added to the upstream request at call time, so the model never sees it.

The full details are in Deploy your own MCP server in the docs.

Step 5: Grant the tools you want, one at a time

Nothing is granted by default, including to you. On the server's permissions, grant the tools each person or agent should use. Start with the read operations. Add writes when someone needs them, and keep deletes for the few people who should have them.

Then connect your client through Statio, as described in Connect a client, and start a new session so the client picks up the server.

Ask the agent to use a tool you granted. The gateway adds the credential on the way out and records the call in the audit log. Then ask for a tool you didn't grant. The gateway refuses it and logs that too.

Step 6: Ship changes as versions

When the API changes, ship a new version from the server's page. Statio fetches the spec again. If the spec, the generator and your settings are all unchanged, it reuses the last image instead of rebuilding.

Each version can run on its own preview URL before you promote it, and you can roll back to an earlier version without a rebuild. A rollback returns the code that ran before. Credentials, grants and the outbound allowlist are current settings and do not roll back with it.

The do-it-yourself route

For a handful of tools, writing the server yourself with the official SDK is a reasonable afternoon. The steps are in How to build an MCP server in Python and How to build an MCP server in TypeScript.

The work is mostly around the tools: hosting it, keeping it in sync with the spec, and keeping the API key out of client config files. Generation saves you more of that than of the code.

Conclusion

You now have a private MCP server generated from your spec, allowed to reach only your API's host, with its tools granted one at a time. When the spec changes, ship a new version.

Next tutorials:

• How to add MCP servers to Claude Code
• How to set up MCP servers in Cursor
• How to build an MCP server in Python
• How to build an MCP server in TypeScript
• How to give an AI agent read-only GitHub access