Serving API Reference to Agents: MCP Servers from OpenAPI Specs

The basic algorithm is short. Load the spec at startup, walk every path and method, and emit a tool per operation.

Naming deserves a rule of its own. When operationId is missing, generators typically synthesize a name from method and path, which means GET /users/{user_id}/repos becomes something like get_users_user_id_repos (Converting OpenAPI specs into MCP servers). Synthesized names are ugly but stable; the bigger risk is drift, where a path rename silently renames a tool and an agent that learned the old name fails. Operation IDs are preferred in code generation for the same reason (OpenAPI best practices, Speakeasy).

A minimal generator, using a small Python MCP server, looks like this:

import json, re, httpx
from mcp.server.fastmcp import FastMCP

SPEC = json.load(open("openapi.json"))
READ = {"get", "head", "options"}
BASE = SPEC["servers"][0]["url"]

def tool_name(op_id, method, path):
    if op_id:
        return op_id
    slug = re.sub(r"[^a-zA-Z0-9]+", "_", path).strip("_")
    return f"{method}_{slug}"

def input_schema(op):
    props, required = {}, []
    for p in op.get("parameters", []):
        props[p["name"]] = p.get("schema", {"type": "string"})
        if p.get("required") or p["in"] == "path":
            required.append(p["name"])
    body = (op.get("requestBody") or {}).get("content", {}).get("application/json")
    if body:
        props["body"] = body["schema"]
        required.append("body")
    return {"type": "object", "properties": props, "required": required}

def build(server, spec):
    for path, item in spec["paths"].items():
        for method, op in item.items():
            if method not in READ:      # writes handled separately
                continue
            name = tool_name(op.get("operationId"), method, path)
            desc = op.get("description") or op.get("summary") or ""
            def handler(arguments, _m=method, _p=path):
                url = BASE + _p
                for k, v in arguments.items():
                    url = url.replace("{" + k + "}", str(v))
                r = httpx.request(_m.upper(), url, params=arguments, timeout=30)
                return r.text[:4000]
            server.tool(name=name, description=desc)(handler)

The handler above is deliberately crude: it passes every argument as a query parameter, which is wrong for path parameters and bodies. Fix that before shipping. The important part is the shape of the mapping, not the twelve lines of URL templating.

Auth lives in the server process, not in the tool schema. Give the MCP server the credential (a scoped token, not a user's session), inject it as a header on outbound calls, and never expose it as a tool argument. Agents write tool arguments into conversation history and logs, so credentials passed as arguments leak by design.

Error handling matters because an agent will retry badly. Return a structured message that names the status code and echoes the API's own error body, and mark 4xx failures as non-retryable in the text. A 400 from a bad payload means the agent should reread the schema; a 429 means back off. If you collapse both into "request failed", the agent guesses.

Some OpenAPI features are lossy in the conversion. Pagination is the standard example: a limit/offset pair converts into two optional integer arguments, and the agent has no reason to know that a page size of 10,000 will time out. Multipart uploads, webhooks and streaming responses have no clean tool equivalent (OpenAPI to MCP conversion). Decide explicitly for each: cap the page size in your handler, skip file uploads entirely for now, or add a separate tool that takes a URL instead of raw bytes. Skipping an operation is a legitimate outcome of the conversion, and it protects the rest of the surface.

There is also a context cost. Every tool definition you expose is context the model has to carry. The MCP client guidance notes that hosts connecting to many servers with hundreds of tools can spend the majority of the window on definitions alone, and recommends progressive discovery: a small search tool that returns names, then a details call for the one tool needed (MCP client best practices). For a single internal API with thirty operations you can ignore this; for a suite of ten internal APIs exposed at once, you cannot.

The default exposure set should be reads only: GET, HEAD and OPTIONS. Writes go behind a confirmation step. The protocol itself frames tools as model-controlled, invoked with a human in the loop to grant approval (MCP tools documentation). Treat that as a floor, not a ceiling: an approval dialog that says "the agent wants to call update_account" tells a human nothing useful.

The write tool should do this instead:

1. Plan. Compute the method, the fully resolved URL and the serialized payload from the arguments.
2. Return the plan. Send back a readable block with the exact method, URL, headers minus the auth header, and the JSON body, plus a one-line summary of what changes.
3. Require a token. Accept a confirmation argument (a nonce the user prints back, or an approval flag set by a human) and refuse to send without it.
4. Send once. On success, return the API response; on failure, return the error and do not silently retry.

{
  "tool": "update_account",
  "method": "PATCH",
  "url": "https://api.example.com/v2/accounts/4481",
  "body": { "billing_email": "[email protected]" },
  "effect": "Changes the billing contact for account 4481.",
  "requires_confirmation": true
}

A second decision rule: writes that are idempotent and cheap (adding a label, posting a comment) can be one-step with a dry-run mode; writes that are destructive or financial (DELETE, refunds, plan changes) should require the exact URL and payload to appear in the approval text the human sees. If those two strings are not on screen when the human clicks approve, the gate is theater.

If your write endpoints call a model themselves (a summarizer, a classifier, an embedding step inside your own service), that is a separate credential from the one the MCP server holds. A single prepaid, OpenAI-compatible endpoint for every model type keeps that plumbing small: Quanta Inference covers text, image, video, audio and embedding models through one API key at https://quantaintelligence.ai/inference.

The spec now has a second reader, and that reader is literal, tireless, and never asks a human for clarification. These edits pay back within a week.

Make operation IDs unique and stable. The operationId must be unique in the document and is case sensitive, and it becomes the generated method or tool name (Speakeasy on OpenAPI best practices). Prefix by resource (accounts_get, accounts_list, invoices_refund) so the agent's tool choice is decidable from the name alone.

Rewrite descriptions to say when to use the operation. A description like "Gets an account" is useless when the API also has accounts_get_by_external_id and accounts_search. Say which one to reach for and which to avoid. API documentation guidance is consistent that reference material must describe what each endpoint is intended to do, not just its method and parameters (Postman on API documentation), and the same standard applies to the tool description because it is the only text the model sees at selection time.

Mark required fields properly. Parameters go in the required array; body properties need required inside the schema. An agent reading an optional-looking field will omit it and get a 422, which is a wasted round trip and a confusing error. The OpenAPI Initiative's guidance to keep a single source of truth matters here: if you generate the spec from code annotations, the required lists must come from the same validation the code runs (OpenAPI best practices).

Use shared component schemas. Inline request body schemas get inferred names and are discouraged by API tooling vendors because those names collide (14 best practices for OpenAPI). A $ref to a named component gives you a clean, reusable argument schema.

Keep examples real and runnable. An example body in the spec becomes the agent's template. Placeholder strings like "string" produce malformed requests.

Treat these as review gates. Docs-as-code practice shows the payoff of blocking merges when docs are missing, since documentation tracked in the same pull request as code stays current (Write the Docs on docs as code). Do the same for the spec: a pull request that changes an endpoint and not its description fails review. The UK government's technical writing team reports that running documentation through the same Git workflow as code keeps it in sync with the product and lets anyone contribute corrections (GOV.UK Technology on docs as code).

Three checks decide whether the server is ready.

First, schema validation. Run the spec through a validator in CI before generating the server, so you never ship a tool with a broken argument schema; validators also catch drift between the implementation and the description when run against live responses (OpenAPI best practices). Second, dry-run every read tool against the real API in a staging environment and look at the arguments the agent actually sends, not the arguments you expected. Third, read the tool list the way the model sees it: names, descriptions, schemas, nothing else. If you cannot decide from that list which tool to call for a given task, neither can the agent.

When you are ready to let a coding agent use the server, point it at the local build first. Clients that support progressive discovery will keep the context cost low, and the layered catalog, inspect, execute pattern from the MCP client guidance is worth imitating even in a single-server setup: search the tool catalog, inspect one definition, then execute (MCP client best practices).

If the goal is the other direction, letting a coding agent build and maintain the API around the spec, the skill library at https://quantaintelligence.ai/skills lets you install one into a coding agent so the same generation and review steps run as part of its workflow.