Guide

How to convert OpenAPI to MCP

An OpenAPI document describes an API. An MCP server lets an agent actually call it. "Converting" one to the other isn't a file-format transform — it's a deterministic mapping from operations to tools, plus the governance layer (risk, scopes, audit) that a raw spec has no concept of. Here's exactly what that mapping does, and how to run it.

What "converting" actually means

An OpenAPI spec is documentation with structure — paths, methods, schemas. It doesn't run anything. An MCP server is a live, callable endpoint: an agent connects to it, discovers a set of tools via tools/list, and invokes them via tools/call. Turning the first into the second means, for every operation you select:

  • Generating a tool name and description the model can reason about.
  • Turning the operation's parameters and request body into a JSON Schema input schema the model must satisfy.
  • Assigning a risk class, so a destructive call doesn't get the same automatic trust as a read.
  • Publishing all of that as an immutable, versioned bundle behind one MCP endpoint.

The mapping rules

Nobody hand-assigns any of this — it's derived deterministically from the spec:

OpenAPIMCP tool
operationIdTool name (camelCase → snake_case)
summary / descriptionTool description (the model's only signal for when to call it — rewrite thin ones)
parameters + requestBodyJSON Schema inputSchema
HTTP methodGET/HEAD → low risk · DELETE → high risk · other writes → medium risk
servers[].urlThe environment's base URL, used at call time

The risk class isn't cosmetic — it's what the policy decision point uses at call time to decide allow, allow_with_confirmation, or allow_with_approval. A spec with only GETs converts to an all-low-risk server; add a DELETE and that one tool comes out high-risk automatically, with no policy authoring required to catch it.

Run the conversion

  1. Sign up — you land in the console with a tenant and a default environment already provisioned.
  2. API Contracts → Upload OpenAPI — paste the spec JSON/YAML or point at a URL. You get back a validation report before anything is generated.
  3. Generate tools — select the operations you want; each becomes a tool using the mapping above.
  4. Create an MCP server, attach the generated tools, and publish a version. You get back a live endpoint:
https://mcpplatform.dev/mcp/srv_XXXXXXXXXX

That's a standard MCP Streamable-HTTP JSON-RPC 2.0 endpoint — initialize, tools/list, tools/call — ready to paste into Claude, ChatGPT, or any other MCP client. For the full walkthrough with a live example spec end to end, see Turn a REST API into an MCP server or the generic Connect Your First API tutorial.

Skip the console entirely

If you'd rather not click through a UI at all, the platform exposes its own conversational MCP server that runs this exact pipeline from inside a chat with an agent — no forms, no clicking. See Create an MCP server from OpenAPI without code.

Working from an older Swagger 2.0 document instead of OpenAPI 3.x? See How to turn Swagger into an MCP server — the same pipeline handles both. Adding MCP to an API that's already in production? See How to add MCP to an existing API.

Start free Read the full tutorial