Your OpenAPI spec is the integration

Someone in the integration meeting asks how many new backend endpoints this needs. It is the right question, and on most AI projects the honest answer is somewhere between "a few" and "a service", which is where the timeline goes.

There is a version where the answer is none. Converting an OpenAPI spec to LLM tools is well-trodden: the OpenAI Cookbook has a walkthrough, and half a dozen libraries do it in a line of code.

What none of them cover is the part that matters once the output is a screen rather than a paragraph. Your spec does not only decide what the model can call. It decides what it can show.

The short answer

Your OpenAPI spec is the integration when the assistant reads it directly to learn which operations exist, what they accept and what they return. No generated client, no new endpoints, no product-specific server code. A human allowlists the operations the assistant may use; everything else stays invisible to the model.

What "the spec is the integration" is not

Three things it gets confused with, each with a real distinction.

It is not MCP. MCP is a transport and a discovery protocol for exposing tools to a model. An OpenAPI document is a description of an HTTP API that already exists. You can put one behind the other, and the choice between them is about how tools are served rather than what they are — a separate question, and one this cluster covers on its own.

It is not code generation. Nothing is scaffolded. No client is emitted into your repo, no types are generated, and there is no build step whose output you then maintain. The spec is read at runtime and turned into a tool manifest in memory. If your spec changes, nothing needs regenerating, which is a genuine advantage and — as the honesty section gets to — a genuine risk.

It is not "the model can call your API". That is the chatbot version, and it is what every library on this SERP builds. samchon/openapi states the pitch plainly (checked 21 August 2026): if you have any HTTP backend and an OpenAPI document, you can make a chatbot. True, and it stops one step short. A chatbot calls the operation and narrates the result. A generative UI layer calls the operation and renders the result, which makes the shape of what comes back part of the contract rather than an implementation detail.

From an OpenAPI spec to LLM tools, in three stages

None of the three touches your backend.

The spec becomes a tool manifest

Each operation in the document becomes a candidate tool. operationId is the tool name — this is the one mechanical detail every library in this space shares — and the parameters become the arguments schema the model fills in. Path, query and body parameters map straight across.

Nothing here is novel and nothing here is where the work is. The spec you already publish for your own client teams is the input.

The allowlist decides which operations exist

A real spec is much larger than the useful subset. The one measured further down describes 173 operations; the integration uses 17. That ratio is normal, and the allowlist is the mechanism: a human names the operations the assistant may use, by operationId, in a config file.

This is not a filter applied for tidiness. An operation absent from the allowlist does not exist as far as the assistant is concerned — there is no tool definition for it, so there is no prompt injection, no reasoning failure and no clever phrasing that reaches it.

The safety classification decides which of those the model sees

Each allowlisted operation gets a safety classification, derived from its verb. The default is one line:

function defaultSafety(method: ManifestTool["method"]): ToolSafety {
  return method === "GET" || method === "HEAD" ? "read" : "disabled";
}

Read operations are offered to the model. Everything else is disabled by default, and disabled means the definition is filtered out before the tool list is assembled — the model is never told the operation is there.

The half of the spec everybody throws away

Every library named on this page consumes the request side of the document. operationId, parameters, maybe a description. The responses section is dropped, and the reason is reasonable: a chatbot only needs to stringify whatever comes back, so the shape of the response is not something it has to plan around.

Change the output from a paragraph to a screen and that section becomes the most important part of the file.

A screen has to be composable from what the operation returns. An endpoint that returns an array of objects, each with a name, a price and a date, can become a comparison, a collection, or a metric row — the data has the arity and the field types those shapes need. An endpoint that returns a single scalar cannot become a comparison no matter how the request is phrased, and an endpoint whose response schema is {"type": "object"} with no properties cannot become anything, because nothing downstream knows what is in it.

Your response schemas are a capability inventory. They tell you which of your endpoints can produce a structured answer and which can only produce a sentence, and they tell you before anyone writes a prompt.

It is usually a shorter list than anyone expects, because response schemas are the part of a spec that teams document last. Turning one into a specific screen is its own subject, and this cluster covers it separately.

What has to be true for this to be safe

Reading a spec at runtime and handing operations to a model is only defensible with the defaults pointing the right way.

Mutating verbs are off unless a human turns them on. GET and HEAD classify as read; POST, PUT, PATCH and DELETE classify as disabled. That is the default for every operation in every spec, applied before anyone reviews anything, so the failure mode of forgetting to configure something is that it does not work rather than that it fires.

It is enforced twice, in two places that do not depend on each other. The agent builds its tool list by filtering to definitions whose safety is read, so a disabled operation is never described to the model. Independently, the executor refuses to invoke a definition classified disabled and returns operation_disabled — so even a tool call that arrives by some other path does not execute. That double enforcement is the same instinct as mutating verbs being disabled by default and it is worth building even though the second check should be unreachable.

The override exists, and pretending otherwise would be dishonest. The classification is per-operation and a human can promote one. The shipped Vaulted integration does exactly this: a policies block reclassifies a single POST as read, because it computes a quote and returns it without persisting anything. So the accurate claim is not that writes are unreachable. It is that an operation reaches the model only if a human both allowlists it and classifies it read — two deliberate, auditable, reviewable decisions in a config file, rather than a default. Treat any such promotion as a security change, because it is one, and it is one of the boundaries in what a generated screen is structurally unable to do.

Where it does not fit yet

Your spec has to be accurate, and most are not. This is the hard prerequisite and it disqualifies more teams than anything else here. A spec that was generated once and has drifted since will degrade a chatbot gracefully — the model narrates whatever it got — and break a UI layer hard, because the screen was planned against a shape the response did not have. If nobody validates your spec against live responses, that is the work to do first, before any of this.

Read-only is load-bearing, and it fights some products. "What happened, why, and what are my options" is read-only by nature and this shape suits it. "Rent the dress" is not, and every session ends in a handoff to your existing flow. In account-based services that handoff is correct behaviour. In commerce it is a bounce, and you should treat that as a reason not to start here.

A large spec needs a human to choose. The allowlist is not something to automate by pattern-matching on verbs. Someone who knows the product has to decide which 17 of 173 operations answer real customer questions, and that is an afternoon of judgement rather than a config change.

No backend changes is not no work. It is honest about your servers and quiet about everything else: the allowlist, the classifications, the declared navigation paths, and a review of what your response schemas can actually support.

A concrete example

Here is the whole of a shipped integration, measured on 21 August 2026.

The directory server/integrations/vaulted/ contains two JSON files that matter. openapi.json is the customer's own spec, unmodified, 3.3 MB, describing 158 paths and 173 operations — 68 GET, 77 POST, 13 PATCH, 12 DELETE and 3 PUT. integration.json is 2,112 bytes and is the entire integration:

{
  "id": "vaulted",
  "type": "openapi",
  "spec": "./openapi.json",
  "baseUrl": "${VAULTED_API_BASE_URL}",
  "include": [
    "getListings", "getListingsById", "getListingsByIdAvailability",
    "postRentalsQuote", "getRentals", "getRentalsById",
    "getConversationsInbox", "getUsersMe"
  ],
  "auth": { "type": "bearer", "credential": "VAULTED_API_TOKEN" },
  "policies": { "postRentalsQuote": "read" },
  "continuations": [
    {
      "intent": "show_listing_details",
      "subjectType": "listing",
      "sourceOperations": ["getListings"],
      "targetOperation": "getListingsById"
    }
  ]
}

That is trimmed — the real file names 17 operations and four continuations — but the structure is complete. include is the allowlist. policies is the one hand-promoted operation, visible in eleven characters. continuations declares the navigation the assistant is allowed to offer: from a listing in a collection, the user may open that listing's detail, because a human wrote that mapping down. There is no inferred navigation.

The claim worth checking is the negative one, and it is a grep rather than an assertion:

grep -ril "vaulted" server/lib/
# no output

Nothing under lib/ mentions the customer. The library that reads specs, builds manifests, classifies safety, runs the agent and validates the wire contains no product-specific code, which is what makes "the spec is the integration" a structural claim rather than a description of one lucky project. Run the equivalent against your own AI integration; the length of that output is the size of the thing you will maintain.

Frequently asked questions

How do you turn an OpenAPI spec into LLM tools?

Read the document, take each operation's operationId as the tool name and its parameters as the arguments schema, and hand the resulting list to the model. Several libraries do this in a line. The part worth your attention is not the conversion — it is deciding which operations belong on the list and what each one is permitted to do.

Do you need MCP if you already have an OpenAPI spec?

Not to make your API callable, no. MCP solves discovery and transport: how a tool server advertises itself and how a host connects. An OpenAPI document already describes operations that exist, so an assistant can read it directly. MCP becomes interesting when several hosts need the same tools, which is a distribution question rather than an integration one.

How do you stop the model calling an endpoint that writes?

Classify by verb and default to closed. GET and HEAD become readable; every other method is disabled, which means no tool definition is generated and the model is never told the operation exists. Enforce it a second time at the point of execution, so a call arriving by any other route is refused rather than run.

What happens if the OpenAPI spec is wrong?

A chatbot degrades quietly, because it narrates whatever it received. A UI layer fails loudly, because the screen was planned against a shape the response did not have. That is a genuine argument against this approach for teams whose specs are generated once and never checked against live responses, and it is the prerequisite to fix first.

Where to start

Open your OpenAPI document and answer two questions before anything else.

1. Is it true? Pick five operations and compare the documented response schema to what the API returns today. If any of the five disagree, that is the project, and everything else waits.
2. Which operations answer a customer's question? Not which are interesting — which appear in the answer to something a person actually contacts you about. That list is your allowlist, and on a large spec it will be a tenth of what is there.
3. What do those operations return? For each one, decide whether the response has the arity and the field types to make a structured answer, or only a sentence. That is your capability inventory, and it is knowable before you write a prompt.

If the answers are yes, a short list, and mostly structured, the shipped integration format and wire schema are what we would show you first — two JSON files, an allowlist, and a lib/ with nothing customer-specific in it. Email hello@uzori.ai and ask for them.