MCP vs OpenAPI: What Each Standard Is For
Short answer: OpenAPI describes an HTTP API so developers and code generators can build against it. MCP packages a service's capabilities so an AI model can use them at runtime. The MCP vs OpenAPI question is not about which one wins. It is about which audience you are serving: humans and tooling at build time, or a model in the middle of a task.
That distinction matters because there is a tempting shortcut going around: "our API already has an OpenAPI spec, so we'll just hand the spec to the model and let it make HTTP calls." It sounds efficient. In practice it burns context, breaks on auth, and produces an agent that can technically see every endpoint and practically use none of them well.
What OpenAPI is actually for
OpenAPI (formerly Swagger) is a machine-readable contract for an HTTP API. It lists every path, method, parameter, request body, response schema, and error code, plus the auth scheme the API expects. That exhaustiveness is the point. A code generator needs every field to produce a typed client, a docs site needs every endpoint to be complete, and a validator needs every schema to catch mistakes before they ship.
The audience is developers and build-time tooling. Nobody expects a human to read a spec file that runs thousands of lines of YAML top to bottom. Machines consume it and produce something usable.
What MCP is for
MCP, the Model Context Protocol, is an open standard for connecting AI agents to tools. An MCP server advertises a list of tools, each with a name, a description written for the model, and an input schema. The agent's client fetches that list, the model picks a tool, and the server executes the call and returns a result the model can work with.
Two design choices separate it from a spec file. First, it is a runtime protocol: the model discovers what it can do at the moment it needs to do it, and the tool list can change between sessions without anyone reconfiguring the agent. Second, it is curated: a good server exposes eight task-shaped tools, not two hundred endpoints. If the server side of this is new to you, start with [what an MCP server actually is](/blog/what-is-an-mcp-server).
Why "just feed the spec to the model" fails
It burns context. An OpenAPI spec is exhaustive by design, and exhaustive is expensive at inference time. Say a spec documents 200 endpoints and each one averages 300 tokens of paths, parameters, and schemas. That is 60,000 tokens of API description sitting in the context window before the model reads a word of your actual task, and most tasks touch three or four endpoints. You pay for the rest anyway, on every turn. The same logic applies inside MCP, by the way, which is why [trimming what gets loaded into context](/blog/reduce-mcp-token-usage) matters there too.
It fails on auth. The spec tells the model that the API uses OAuth 2.0 with certain scopes. It cannot run the authorization flow, store the token, refresh it when it expires, or keep the secret out of the transcript. A model reading YAML knows how you are supposed to authenticate. It has no way to actually do it. An MCP server owns that problem: credentials live server-side, and the model calls tools that arrive already authenticated.
It describes requests, not work. Even with the full spec in context, the model still has to compose raw HTTP correctly: pagination, rate limits, retries, chaining a lookup call into an update call. Every one of those steps is a chance to fail. An MCP tool wraps the sequence instead. The model calls a search tool with a query string, and the server deals with the query parameters, the cursor, and the rate-limit responses.
MCP vs OpenAPI, side by side
If you are weighing an API spec vs MCP for agent access, this is the split.
| OpenAPI | MCP | |
|---|---|---|
| What it is | A description document | A runtime protocol |
| Built for | Developers, codegen, docs tooling | AI models and agent clients |
| Consumed at | Build time | Inference time |
| Coverage | Every endpoint, exhaustive | Curated tools, selective |
| Auth | Documents the scheme | Performs and manages the sign-in |
| Result handling | Up to your client code | The server shapes results for the model |
They complement each other
Here is the part the "versus" framing hides: many MCP servers are wrappers around OpenAPI-described APIs, and that is a healthy pattern. The spec is the best possible input for building a server. It hands you the endpoints, the schemas, and the auth requirements. Your job is to collapse them into a handful of tools an agent can actually use, write descriptions a model can act on, and handle credentials properly.
So if you own an API: keep the OpenAPI spec, your human developers still need it. Add an MCP server on top for agents. If you are on the consuming side, check whether the tool you want already ships one before you reach for the raw spec. The [curated MCP directory](/discover) tracks MCP status per listing, so that check takes a minute.
For the broader comparison of the protocol against plain HTTP APIs, beyond just the spec format, see [MCP vs API](/blog/mcp-vs-api).
Frequently asked questions
Can I generate an MCP server from an OpenAPI spec?
Yes, and generators are a reasonable way to scaffold one. But a one-to-one mapping of endpoints to tools recreates the context problem inside MCP: 200 endpoints become 200 tool definitions the model loads every session. Generate, then cut. Keep the tools that map to real agent tasks and merge or drop the rest.
Does MCP replace OpenAPI?
No. They serve different consumers. OpenAPI stays the contract for developers and code generation, and MCP is the interface a model uses at runtime. Most well-built MCP servers quietly depend on a well-documented API underneath.
Is OpenAPI useful for AI agents at all?
As source material, very. It is the fastest way to understand what an API can do when you are building agent tooling. As a runtime interface for the model itself, no: a spec cannot execute a call, hold a token, or shrink itself down to the parts a task needs. That translation step is exactly what an MCP server is for.