MERLONIX

How to Convert a REST API into an MCP Server (OpenAPI to MCP)

If you have a REST API and an OpenAPI spec, you have already done the hard part of describing your product to a machine. What you probably do not have is a way for an AI agent to use it. Agents do not call REST endpoints directly — they call tools exposed over the Model Context Protocol (MCP). If there is no MCP server in front of your API, agents cannot see it, cannot reason about it, and cannot call it. This guide walks through converting an OpenAPI or Swagger spec into a working MCP server, what the conversion actually does under the hood, and what to check before you point an agent at the result.

Why Agents Need MCP, Not REST

An agent that wants to call your API needs three things a raw OpenAPI document does not hand over cleanly: a stable tool name it can reference in a function call, a description it can use to decide whether this tool is the right one for the current step, and a typed input schema it can use to construct a valid call without guessing at parameter shapes. MCP is the protocol that packages those three things into a discoverable, typed tool list an agent's runtime can query and call.

REST APIs were built for human developers reading documentation and writing client code by hand. MCP servers were built for a different consumer: an autonomous agent that has to pick the right tool out of a list, at runtime, with no human in the loop. Converting REST to MCP is the adapter layer between the two worlds — it does not change your API, it exposes the API you already have in a shape agents can act on.

What the Converter Does

The free API-to-MCP converter takes an OpenAPI 3.x or Swagger 2.0 spec as JSON — paste it directly, or give a URL and the tool fetches it for you (SSRF-guarded, capped at 2 MB) — and runs a deterministic transform. Nothing is stored server-side; the conversion happens, you get the output, and that is the end of it.

The mapping from REST operation to MCP tool is straightforward once you see it laid out:

  • operationId becomes the tool name. This is the identifier the agent will actually invoke, so an OpenAPI spec with clear, unique operationIds (listAssets, createAsset, getAssetById) produces a clean tool list. Vague or duplicate operationIds carry straight through as vague or duplicate tool names.
  • summary becomes the tool description. This is the single most important field for agent tool selection — an agent reads this text to decide whether a tool matches what it is trying to do. A missing or thin summary means the agent is choosing blind.
  • parameters and requestBody become the JSON-Schema inputSchema. The converter inlines $ref references and merges path-level parameters with operation-level parameters, so the resulting schema is self-contained and correctly typed rather than a tangle of pointers the agent's runtime has to resolve itself.
  • Security schemes become the auth binding on the generated server, so the server knows how to attach credentials to the real API calls it proxies.

The result is not a document about your API — it is a tool definition an MCP client can list, describe to a model, and call.

The Three Outputs

Running a spec through the converter produces three artifacts:

  1. MCP tool definitions — the typed, described tool list described above, one per API operation.
  2. A .well-known/mcp.json manifest — a discovery document describing the server, so an MCP client (or a monitor) can find and identify it.
  3. A runnable Node (stdio) MCP server, built on the official @modelcontextprotocol/sdk, that proxies each tool call through to your real REST API.

That third artifact is the one that matters most in practice: it is not pseudocode or a template you have to finish. It is a server you can run.

You Run It Yourself, Today

The generated server is yours to operate: download it, set your API's base URL and an optional API key, and point your MCP client at it. Merlonix does not run or host the server for you right now — that is on the roadmap as a hosted-conversion option, but it has not shipped. What has shipped is the generator, the grading, and a free one-shot health check you can run against a server once it's live (more on that below).

One forward-looking detail worth knowing: the generated server is built on the official MCP SDK rather than a hand-rolled transport, so when the stateless MCP transport spec lands (2026-07-28), upgrading the SDK dependency picks up the new transport without touching your tool definitions.

The Readiness Grade and the Tool-Poisoning Check

A converter that only reshapes your spec into tool definitions is doing half the job. The other half is telling you whether the result is safe to hand to an autonomous agent — which is why the converter also grades the output A through F across seven dimensions.

The check that leads that grade is tool poisoning. An agent reads a tool's description verbatim as part of its own reasoning context — which means a hidden instruction smuggled into an OpenAPI summary field (an "ignore previous instructions" phrase, a request to read your .env file, an <important>-style block, even invisible zero-width text) can hijack the agent that calls it. The converter scans every generated tool's name and description for these injection patterns, and a poisoning flag caps the grade so a server carrying one can never read as ready, regardless of how clean everything else looks.

The grade also weighs auth posture (no auth, versus static API keys, versus OAuth 2.1), how many of your tools can write — POST, PUT, PATCH, DELETE — versus only read, how many inputs are left untyped, and whether the resulting tool surface is small enough for an agent to select from well. It flags operations with no description at all, since an undescribed tool is one an agent is choosing blind, and it surfaces every write operation so you can review what an agent would actually be able to change before you let it. The whole scan is deterministic and nothing is stored. For the deeper mechanics of the grade itself, see the agent-readiness checker.

Tool-Count Discipline

Bigger is not better here. An agent's ability to select the right tool degrades sharply once the tool list runs past roughly 40–50 entries — every additional tool is one more competing option the model has to weigh when it decides what to call next. The converter caps generation at 100 tools (MAX_MCP_TOOLS) and warns you when your API is over that limit.

The practical move if your API has more operations than that is not to fight the cap — it's to be selective. Expose the highest-value read and action operations as MCP tools, not a mechanical one-to-one mirror of every endpoint in your spec. A focused, well-described 20-tool surface will outperform an exhaustive, thinly-described 150-tool surface every time an agent has to choose between them.

Scope and Honest Limits

Two limits worth knowing before you start:

  • JSON only, for now. The converter reads OpenAPI/Swagger as JSON. If your spec is YAML, export or convert it to JSON first. YAML input is coming but not shipped.
  • Node-stdio server today. The generated server runs over stdio, which is the right shape for a local MCP client. A Cloudflare Worker / Streamable-HTTP variant — for serving the MCP server itself over the network — is a planned fast-follow, not available yet.

Neither limit blocks the core use case: taking a JSON OpenAPI spec and producing a server your MCP client can run locally today.

The Lifecycle: Generate, Validate, Monitor

Converting a spec is a one-time event; keeping the result trustworthy is not. Three steps, in order:

Generate. Run your OpenAPI or Swagger JSON through the converter to produce the tool definitions, the manifest, and the runnable server.

Validate. The same conversion is graded A–F for agent-safety and readiness — tool poisoning, auth posture, write-operation exposure, description coverage, tool count — before you wire an agent to it.

Monitor. Once your MCP server is actually running, a static grade from generation day stops being enough — schemas change, deployments regress, servers go down. Merlonix's MCP-server health monitor runs a real MCP handshake against your live server on a schedule: the JSON-RPC initialize call and a tools/list call, the same sequence a real MCP client performs. It alerts on downtime, a failed handshake, a latency regression, or — the failure mode that is easy to miss and breaks every agent calling the server — silent tool-schema drift, where a tool gets added or removed, or an input schema changes shape, without anyone touching the client side. The one-shot check is free; continuous scheduled monitoring is on a paid plan.

Generate without validating and you might ship a poisoned tool. Validate without monitoring and you find out about drift only when an agent starts failing in production.

Self-Dogfood

Merlonix ran its own /v1/openapi.json — 13 paths — through the converter. The output was 23 correctly-named MCP tools (listAssets, createAsset, getAsset, and so on), a base URL of https://api.merlonix.com, and 13 write operations flagged for review. That is the same conversion path described above, run against a real, shipping API rather than a sample spec.

Try It

If you have an OpenAPI or Swagger document sitting next to your REST API, the fastest way to see whether agents can already use your product is to run it through the free API-to-MCP converter — no signup required. Check the readiness grade before you connect an agent to the result, and once the server is live, point the MCP health checker at it to confirm the handshake actually works. If you're building or operating MCP servers as a regular part of your work, the MCP server developers page covers the rest of the toolchain.