MCP vs OpenAPI: they answer different questions
The comparison is framed as a replacement and it is not one. One describes an API to people and compilers. The other hands a running agent a set of things it may do.
The question gets asked as though one is replacing the other, and the framing is wrong in a way that leads teams to build the wrong thing.
OpenAPI is a description. It is a document that says what your API accepts and returns, read by humans, code generators, linters and documentation tools. It is static, it is versioned, and it describes the whole surface whether or not anyone uses it.
MCP is a protocol. It is a live conversation between an assistant and a server, in which the server offers a set of tools and the assistant calls them while it works. It is dynamic, it is scoped to a session, and it carries only what an agent should be able to do right now.
One is a blueprint. The other is a set of keys. Asking which to use is like asking whether to have architectural drawings or door access.
Why the comparison keeps happening
Because in practice a lot of MCP servers are generated from OpenAPI documents, which makes them look like two formats for the same thing.
They are not, and the generation step is doing real work. It is selecting which operations become tools, naming them for an audience that reads names rather than paths, writing descriptions aimed at a model deciding which tool to reach for, and deciding what an agent is allowed to touch. A spec describes 300 endpoints. A good MCP server might expose 30 of them.
That selection is the product. If your MCP server is a mechanical one-to-one dump of your spec, you have converted a format and skipped the part that mattered.
What OpenAPI is better at
Being complete. A spec covers every operation including the ones nobody should call from an agent, the deprecated ones, the internal ones. Completeness is the point. It is the contract.
Generating things. Documentation, client libraries, mock servers, validation middleware, test scaffolding. Every one of those wants the full typed surface, and none of them wants a curated subset.
Being reviewed. A spec sits in a pull request. Someone can see that an operation gained a required parameter. There is no equivalent review surface for "what my agent can do today" unless you build one.
Living without a runtime. A spec is a file. It works when nothing is running, which is how a developer reads your API at 2am before deciding to integrate.
What MCP is better at
Being current. An agent asking a live server gets the answer as of now. A spec pasted into a context window is a snapshot that started going stale the moment it was pasted.
Being selective. Context is finite and expensive. A protocol that lets an agent ask for one endpoint's detail beats one that requires it to hold a megabyte of JSON to answer a question about one call.
Executing. This is the part with no OpenAPI equivalent. A spec tells an agent what a request would look like. A tool call makes the request and returns the response, which collapses the loop between writing code and finding out whether it works.
Carrying the things a spec cannot. Your written guides, your changelog, the real method names in your published SDK. None of that is in your OpenAPI document, and all of it changes what an agent writes.
The relationship in one line
Your OpenAPI document should be the source both come from, and your MCP server should be a curated projection of it.
That ordering matters. Teams that hand-build an MCP server separately end up with two definitions of their API that drift, and the agent-facing one drifts faster because nothing compiles against it. Teams that generate the tools from the spec get one source of truth and a curation layer on top.
The curation layer is not optional, and it is where the judgement lives:
Which operations become tools. Exclude anything irreversible, anything administrative, anything an agent has no business calling. The exclusion list you wrote for your public SDK is usually close to right.
What the tools are called. A tool name is read by a model choosing between options. create_invoice is a choice. postV1InvoicesCreate is a transport detail.
What the descriptions say. This is the highest-leverage text in the whole system and it is usually copied from a spec summary written for a documentation page. A tool description is a decision aid: when should the model use this instead of the other one.
When you need only one
You need only OpenAPI if nothing is calling your API through an assistant. That is a shrinking set, and it is a real set.
You need only MCP if you are exposing something that is not an HTTP API at all, which is the case for plenty of MCP servers: file systems, databases, internal services with no public contract. There is no spec to generate from, and hand-writing the tools is correct.
For an HTTP API with an OpenAPI document, wanting one and not the other is almost always a sequencing question rather than a choice. The spec comes first because everything else derives from it.
The practical test
Ask what happens when you add an endpoint.
If your documentation, your client libraries and your agent tools all update from that one change, the relationship is right. If adding an endpoint means editing a spec and then separately editing an MCP server, you have two sources of truth and you will find out which one is stale at the worst moment.
That is the whole argument for generating both from one document, and it is why Octri treats the spec as the input and the docs, the SDKs and the MCP server as outputs of it. One change, four surfaces, no drift between them.
If you want the mechanics of the second half, generating an MCP server from an OpenAPI spec covers the setup. And if you are not sure your spec is in a state to generate anything useful yet, the spec audit scores it against the fourteen rules that decide, free and without an account.
