MCP vs OpenAPI
OpenAPI is the option most teams already own and forget they own. It describes an HTTP API; MCP specifies how a model-facing host discovers and calls a tool. The axis is who each document is written for: OpenAPI is written for programmers and their code generators, MCP for a model and its host at runtime. The two are also historically linked, because the original ChatGPT plugin manifest was an OpenAPI document, and they collide at the same wall from opposite sides: the context window.
Pick OpenAPI if the tools are an HTTP API you own and the consumer is your own agent: generate tool definitions from the document you already publish, and skip the extra hop, the extra deployment and the OAuth proxy in front of your own API. Stay on MCP if the consumer is a client you do not control, if the far end is not HTTP at all (a local file system, a subprocess, a desktop app), or if you want discovery, change notification and result caching as protocol features rather than as conventions you maintain.
Side by side
MCP vs OpenAPI at a glance
| MCP | OpenAPI | |
|---|---|---|
| What it describes | A model-facing protocol: how a host discovers, calls and caches tools, resources and prompts | An HTTP API: paths, methods, parameters, schemas, auth schemes, servers |
| Audience | A model and its host, at runtime | Programmers, code generators and documentation tooling |
| Tool-call semantics | ✓ defined: tools, arguments, results, annotations | ✗ none. You or a generator must translate the document into tool definitions |
| Transport | stdio subprocess or Streamable HTTP; anything else is a custom transport | HTTP by definition. A non-HTTP far end is out of scope |
| Discovery | ✓ server/discover is mandatory for servers since 2026-07-28 | URL convention, not protocol |
| Change notification | subscriptions/listen, opt-in per notification type such as toolsListChanged | ✗ nothing in the specification: you republish the document |
| Result caching | CacheableResult with ttlMs and cacheScope required on list results; deterministic tool ordering requested for prompt-cache hits | HTTP caching, at the API layer; the description says nothing about it |
| The context-window problem | Definitions are loaded upfront; Anthropic measured one workload at 150,000 tokens and cut it to 2,000 with code execution | Real documents are routinely far too large to put in a context window, and trimming them is your job |
| Authorization | Optional. Over HTTP, OAuth 2.1 resource-server model with RFC 9728 metadata and RFC 8707 resource indicators; token passthrough is forbidden | Auth schemes are described, not implemented and not enforced |
| Custodian and licence | MCP a Series of LF Projects, LLC (Agentic AI Foundation, Linux Foundation). ✓ Apache-2.0 | OpenAPI Initiative, a Linux Foundation project. ✓ Apache-2.0 |
| Current version | Revision 2026-07-28, date-based and declared on every request | OAS 3.2.0 is the current line; 3.1.2 is the newest 3.1.x patch |
| Ecosystem | Tier 1 SDKs with, per the maintainers' own release post, close to half a billion downloads a month | ✓ a decade of registries, code generators and tooling, and effectively universal for public HTTP APIs |
| Price | No price: it is a spec | No price: it is a spec |
| Best for | Tools consumed by clients you do not control, including non-HTTP and local tools | An HTTP API you already document, consumed by your own agent |
Sources: OpenAPI specifications · OpenAPI releases · MCP specification · Anthropic on code execution with MCP. Compiled August 2026.
Where OpenAPI wins
You already wrote it
If the tools you want an agent to use are endpoints you publish, the description exists, the schemas are already reviewed, and the codegen pipeline is already in CI. Generating tool definitions from that document is a build step, not an architecture. MCP's value is decoupling the tool author from the model operator; when both are you, the decoupling buys nothing and the OpenAPI route removes an entire component from the diagram.
Nothing new to deploy, and nothing new to attack
Putting an MCP server in front of your own REST API adds a hop, a deployment and, if it brokers third-party credentials, an OAuth proxy. That last one is not hypothetical work: MCP's security guidance documents the confused-deputy attack against exactly that shape, in which a proxy using a static client ID with dynamic client registration and a consent cookie lets an attacker harvest an authorization code, and the mitigations are normative (per-client consent before forwarding, exact-match redirect URI validation, single-use server-side state, and signed __Host- prefixed consent cookies). Calling your own API directly skips the whole class.
3.2.0 moved toward streaming
The current line, OAS 3.2.0, published 19 September 2025, added multipurpose and nested tags, more HTTP methods, and streaming support for sequential media types such as server-sent events, with 3.1.2 as the newest 3.1.x patch and 3.0.4 and 3.1.1 also published.
Where MCP still wins
OpenAPI cannot describe a far end that is not an HTTP API. A local file system, a client-launched subprocess, a desktop application: MCP covers those with stdio, and OpenAPI has no answer. It also has nothing model-facing at all. There is no notion of a tool call, no agent lifecycle, no consent model and no way to tell a client that the tool list just changed, so everything above the description layer is code you write and re-write per client. If the consumers are clients you do not control, that work multiplies by the number of clients, which is the exact cost MCP exists to remove.
The deprecations cut both ways, too. MCP's 2026-07-28 revision is the only side of this comparison doing anything about token cost at the specification level: ttlMs and cacheScope are now required on tools/list, prompts/list, resources/list, resources/read and resources/templates/list, and servers are asked to return tools in a deterministic order to improve prompt-cache hit rates. An OpenAPI document has no equivalent, so shrinking it to fit a context window stays a manual, per-agent job.
Replacing an MCP server with OpenAPI-generated tools
The path that works:
1. Inventory what the server exposed. Tools usually map to endpoints. Resources, prompts and elicitation usually do not, and that is where the work hides.
2. Generate, then prune hard. A full document turned into tool definitions is the token problem in a new costume. Select the endpoints an agent actually needs and drop the rest before the first request.
3. Own the authorization yourself. You lose MCP's normative rules, including the requirement that a server must not accept any token that was not explicitly issued for it. Keep audience-bound tokens anyway; the attack does not disappear with the protocol.
4. What does not move. Change notification, list caching semantics, elicitation and anything a third-party client was reaching over MCP. If a client you do not control was using that server, this is not a migration, it is a breaking change for someone else.
Common questions
FAQ: MCP vs OpenAPI
Can I turn an OpenAPI document into agent tools?
Yes, and it is the oldest path in this category: the original ChatGPT plugin manifest was an OpenAPI document. Because OpenAPI gives you paths, methods, parameters and schemas, a generator has enough to emit tool definitions. The hard part is not syntax, it is size. Real OpenAPI documents are routinely far too large to put in a context window, which is the same token problem MCP has, one layer down. Select the endpoints an agent actually needs and generate from that subset rather than from the whole document.
Which is more stable, OpenAPI or MCP?
OpenAPI, by a wide margin, and its stewardship is comparable: the OpenAPI Initiative is a Linux Foundation project and the specifications are Apache-2.0, with 3.0.4, 3.1.1, 3.1.2 and 3.2.0 all published on the same conservative line. MCP is also Apache-2.0 under the Linux Foundation now, and it has a real policy in date-based revisions and a minimum twelve-month deprecation window, but revision 2026-07-28 removed the initialize handshake and protocol-level sessions and deprecated Roots, Sampling and Logging in one release. If interface stability is the priority, that difference is the answer.
Is OpenAPI enough on its own for an agent?
Only if you are willing to write the model-facing half yourself. OpenAPI has no notion of a tool call, no agent lifecycle, no consent model and no way to tell a client that the available tools just changed. It also cannot describe a far end that is not an HTTP API, so a local file system, a client-launched subprocess or a desktop application is out of scope entirely. For your own agent calling your own API it is usually enough. For clients you do not control, everything OpenAPI leaves out becomes work you repeat per client.