How to turn an OpenAPI spec into MCP tools

If your API already publishes an OpenAPI (formerly Swagger) specification, you're most of the way to an MCP server. An OpenAPI spec describes every endpoint, its parameters, and its responses in a machine-readable format — which is exactly what an AI client needs to call a tool. This guide explains how each part of a spec maps to MCP, what gets transformed, and how to generate a working server without writing code.

Why OpenAPI is a perfect source for MCP

Both OpenAPI and MCP exist to describe capabilities in a structured way. OpenAPI tells human developers and codegen tools how to call an API; MCP tells AI models how to call a tool. The overlap is large: an operation's inputs and a tool's input schema are nearly the same thing. That's why converting one to the other is mostly a mechanical mapping.

How each part of the spec maps to a tool

Operations → tools

Every path/method combination in your spec — like GET /products/{id} — becomes a single MCP tool. An API with 30 operations yields up to 30 tools.

operationId → tool name

The operationId field becomes the tool's name (e.g. getProduct). If a spec omits it, a name is derived from the method and path. Clear, verb-based operation IDs make the model far better at picking the right tool.

summary / description → tool description

This is the text the model actually reads to decide whether a tool fits the user's request. Good descriptions in your spec translate directly into a smarter agent. Vague ones lead to wrong tool choices.

parameters & requestBody → input schema

Path parameters, query parameters, and the request body schema combine into the tool's input JSON schema. The model fills these in when it calls the tool. Consider this snippet:

paths:
  /products/{id}:
    get:
      operationId: getProduct
      summary: Fetch a single product by its ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }

That becomes a tool named getProduct, described as "Fetch a single product by its ID," with one required string input called id.

Doing it with Cast

Rather than hand-coding the mapping, you can upload the spec and let Cast generate the tools. Point it at a file or a URL like https://api.example.com/openapi.json:

Once parsing completes, every operation appears as a toggleable tool. This is where you decide what agents can actually do — enable the reads, leave destructive writes off until you've tested:

Configure how Cast authenticates to your API, then grab the MCP URL from the Connect tab:

{
  "mcpServers": {
    "products-api": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.getcast.io/products-api-cmpz99kk01"
      ]
    }
  }
}

What doesn't map cleanly (and how to handle it)

• Auth — OpenAPI describes security schemes, but you still supply the actual credentials. Cast handles this in the Configure tab.
• Huge specs — exposing hundreds of tools can overwhelm a model. Curate down to the operations that matter.
• Complex polymorphic bodies — deeply nested oneOf/allOf schemas still work, but simpler inputs lead to more reliable tool calls.

Frequently asked questions