OpenAPI to MCP, Turning a Spec Into an MCP Server

How operations map to tools

An OpenAPI operation has a method, a path, parameters, a request body and responses. An MCP tool has a name, a description and an input schema. The mapping is direct.

• The operationId becomes the tool name, such as listInvoices or cancelBooking.
• The summary and description become the tool description.
• Path, query and body parameters merge into one input schema.
• The success response schema tells the model what it gets back.

Schemas in components become shared definitions, and enums carry over as allowed values.

Fix the spec before you convert it

Specs written for human developers often lack what models need. A few edits make a large difference.

• Give every operation a clear operationId with a verb and an object. Generated names such as get_api_v1_items_id confuse models.
• Write descriptions that say when to use the operation and what it changes, not only what it is.
• Mark destructive operations clearly, such as deletes, cancellations and payments.
• Add examples to parameters and bodies, because models copy them.
• Use enums instead of free text where values are fixed.
• Describe error responses, so the model understands why a call failed and what to try next.

Choose which operations become tools

Large APIs have hundreds of operations. Agents choose worse from long lists, and some operations should never be in an agent's hands. Start with read operations that answer real questions, add a few write operations that save real work, and leave admin operations out. Group tools into separate servers by audience if needed, for example one for support and one for finance.

Authentication and permissions

The MCP server calls your API on behalf of the agent, so it needs credentials. Do not give it one admin key. Issue a key per agent or per user, map scopes to the tools the key may see, and keep rate limits on every key. Put the servers behind one mcp gateway so permissions and logs live in one place.

Keeping spec and tools in sync

The most common failure of hand converted servers is drift. The API gains a required field, the tool does not, and every agent call starts failing. The fix is to treat the OpenAPI document as the single source and regenerate the tools whenever it changes, the same way you regenerate docs and tests.

Doing it with APIGenerator

Upload your OpenAPI 3.0 or 3.1 file on the openapi generator page. APIGenerator generates the implementation if you need one, the docs, contract tests and a custom mcp server whose tools follow your operations, with keys, scopes, limits and logs. When you upload a new version of the spec, all of it updates together. For background on the protocol itself, read what is an MCP server.