Protocols8 min read

Turning an OpenAPI spec into an MCP server

Each OpenAPI operation maps to one MCP tool, with parameters becoming the input schema — so the scaffold is generatable, but auth, pagination and error semantics still need a human.

The shapes line up

An OpenAPI operation has an id, a summary, typed parameters and a request body. An MCP tool has a name, a description, and a typed input schema. The correspondence is close enough that the mechanical part of the work is genuinely mechanical.

operationId becomes the tool name. The summary becomes the description the model reads when deciding whether to call it. Path, query and body parameters flatten into one input object.

Where it gets awkward

Naming. operationId is optional, and specs that omit it leave you generating names from method and path — which produces tools no model will pick correctly. Missing ids are the single most common reason an operation gets skipped.

$refs. Internal refs resolve fine. External refs mean fetching another document, which is both a performance problem and, for a tool that accepts arbitrary URLs, a security one.

Auth. A generator cannot know your credentials or which environment you are targeting. The honest output is an env-var stub wired into the right header, documented in the README.

Pagination and errors. OpenAPI describes response shapes, not what to do about them. Whether to auto-page, how to surface a 429 — that is design work.

Descriptions decide whether tools get used

The model picks tools by reading descriptions. listPets with the description "List all pets" is fine. getData with no description is dead weight — the model cannot tell when it applies.

Improving your OpenAPI summaries improves your MCP server for free. It is the highest-leverage edit available before generating anything.

How far generation gets you

A generated scaffold that compiles, runs, completes the MCP handshake and exposes typed tools is roughly the first day of work. It is not a production server: no retry policy, no rate limiting, no pagination, no auth refresh.

That is a real head start and a real remaining gap, and it is worth being precise about which is which.

bash

# Generate a scaffold from any discoverable spec
npx tregix-agent-check yourapi.com --out ./generated

cd generated/mcp-server
npm install && npm run build && npm start

Does this apply to your site?

The free checker runs this check and eighteen others, then generates the files to fix whatever fails.

Run the checker