MCP vs OpenAPI: What's the Real Difference?

MCP vs OpenAPI is one of the more common points of confusion for anyone wiring an AI agent up to a real API, because both terms describe how software talks to an API, just from opposite directions. One is a document format read by developers ahead of time. The other is a protocol a model uses while it works. Confusing the two usually means rebuilding something nobody needed to rebuild.

OpenAPI describes an HTTP API in a machine-readable document, meant to be read ahead of time by developers and their tools. MCP (the Model Context Protocol) is a runtime protocol that lets an AI application discover and call tools over JSON-RPC 2.0 while a model works. In practice, a working OpenAPI document is usually the input that produces an MCP server, so the two end up on the same project more often than against each other.

MCP vs OpenAPI at a glance

Here is where OpenAPI and MCP actually diverge, drawn from the two specifications and from Scalar's own side-by-side comparison of the two.

OpenAPI: describing an HTTP API

The OpenAPI Specification (OAS) is the standard for describing HTTP APIs: paths, parameters, request and response schemas, and security schemes, all in one JSON or YAML document maintained by the OpenAPI Initiative under the Linux Foundation. The latest published version is OAS v3.2.1, dated 10 September 2026. By the specification's own description, OpenAPI "allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic." It powers API reference docs, generated SDKs, mock servers and tests, built for a developer who reads it once and writes code that runs the same way every time.

MCP: a runtime protocol for tool calls

The Model Context Protocol standardizes how AI applications connect to external tools and data. Anthropic introduced it in November 2024, and it is now governed by the Linux Foundation's Agentic AI Foundation. An MCP server offers tools (functions a model can call), resources (data the application can read) and prompts (templated workflows a user can pick), exchanged as JSON-RPC 2.0 messages over stdio for local servers or Streamable HTTP for remote ones.

The current specification revision, 2026-07-28, changed the protocol's shape in ways documented in its own changelog: it removed the initialize handshake and protocol-level sessions, making every request self-contained; it added a server/discover method that servers must implement to advertise supported versions and capabilities; and it reclassified the Roots, Sampling, and Logging features, along with the older HTTP+SSE transport, as Deprecated. Any host application that speaks MCP, including Claude, ChatGPT, Cursor, and VS Code, can use any MCP server without custom integration code written for that specific server.

How an OpenAPI document becomes an MCP server

Converting the two is mostly a mapping exercise, and most teams with an existing API start here rather than writing an MCP server from scratch. In Scalar's mapping guide, an OpenAPI operation's operationId becomes the MCP tool's name, its summary and description become the tool's description (the text a model actually reads before deciding whether to call it), its path, query and header parameters plus request body become one JSON Schema inputSchema, and its security scheme becomes server-side configuration that the model never sees. Read-only fields such as a server-assigned id are dropped from the input schema entirely, since an MCP tool input is only ever a request, never a response.

For a real GET /planets operation, Scalar's worked example shows the tool definition an MCP client actually receives from tools/list:

{
  "name": "getAllData",
  "title": "Get all planets",
  "description": "Get all planets\n\nIt's easy to say you know them all, but do you really?",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": { "type": "integer", "default": 10, "description": "The number of items to return" },
      "offset": { "type": "integer", "default": 0, "description": "The number of items to skip" }
    }
  }
}

Pasting the whole OpenAPI document into a model's context instead of generating tools from it does not hold up at scale. Scalar's own benchmark found the Zoom Meetings OpenAPI document ran to roughly 296,000 tokens, more than a 200,000-token context window, and every task attempted that way failed; a native MCP server with 183 tools still cost about 89,000 schema tokens, while a search-then-execute design used around 400.

A few open source tools now automate this conversion. openapi-mcp-generator, an MIT-licensed CLI with 640 stars on GitHub, takes an OpenAPI 3.x document and generates a typed TypeScript MCP server for stdio, SSE, Streamable HTTP, or a deployable Cloudflare Worker:

npx openapi-mcp-generator --input ./openapi.json --output ./my-mcp

Its arguments are validated against each tool's JSON Schema before any request reaches the upstream API, and credentials fail closed when a required one is missing rather than calling the API anyway. Version 5.0 moved generated servers onto the MCP TypeScript SDK v2 and added support for specification revision 2026-07-28 while still serving older, 2025-era clients. The directory mcpservers.org lists 594 MCP servers built specifically around OpenAPI, Swagger, and Postman sources, including one from Tyk Technologies, as of this writing.

Verdict by use case

• Maintaining an API that other programs already call directly: OpenAPI wins. Nothing about MCP changes how existing SDKs, mobile clients, or partner integrations talk to it.
• Want Claude, Cursor, or ChatGPT to call the API for a user: MCP wins, built or generated from the existing OpenAPI document. A model needs tools/list and a JSON Schema inputSchema to decide what to call, and OpenAPI alone gives it nowhere safe to hold a credential.
• Starting an API with nothing documented yet: write the OpenAPI document first. Every converter in this space, from openapi-mcp-generator to Scalar's hosted servers, reads OpenAPI as its source of truth, so one well-written document produces both the human-facing docs and the MCP server.
• Exposing something that is not really an HTTP API, such as a local filesystem or a database query: skip OpenAPI and write the MCP server directly. Some MCP servers, as Scalar notes, never wrap an API at all.

What's new (as of 26 October 2026)

• The OpenAPI Specification reached v3.2.1 on 10 September 2026, published by the OpenAPI Initiative under the Linux Foundation.
• MCP's specification revision 2026-07-28 removed the initialize handshake and made the protocol stateless per request, added the required server/discover method, and reclassified Roots, Sampling, Logging, and the HTTP+SSE transport as Deprecated, per the protocol's own changelog.
• openapi-mcp-generator shipped version 5.0, moving generated servers onto the MCP TypeScript SDK v2 with support for specification revision 2026-07-28 alongside older 2025-era clients, and adding a Cloudflare Worker deployment target.
• mcpservers.org currently lists 594 MCP servers built around OpenAPI, Swagger, and Postman sources.

Key takeaways

• OpenAPI describes an HTTP API for programs and people to read ahead of time; MCP is a runtime protocol that lets a model discover and call tools during a conversation.
• MCP's specification revision 2026-07-28 made the protocol stateless per request and removed the initialize handshake, among other changes in its changelog.
• A clean OpenAPI document, with a stable operationId and model-friendly descriptions, is usually the fastest path to a working MCP server.
• Security schemes in OpenAPI map to server-side configuration in MCP, not to tool inputs: a model should never hold the API credential itself.
• Pasting a full OpenAPI document into a model's context instead of generating tools from it can cost hundreds of thousands of tokens and fail outright, per Scalar's own benchmark.

FAQ

Does MCP replace OpenAPI or REST APIs?

No. An MCP server is usually a thin layer that calls an existing REST API on a model's behalf. REST APIs keep serving existing apps, SDKs, and partner integrations, and MCP adds another way for AI applications to reach the same capabilities, per Scalar's MCP vs API guide.

Can I generate an MCP server automatically from an OpenAPI document?

Yes. Tools such as openapi-mcp-generator take an OpenAPI 3.x document and output a ready-to-run TypeScript MCP server for stdio, SSE, Streamable HTTP, or a Cloudflare Worker, validating arguments against JSON Schema before they reach the API. Swagger 2.0 documents need converting to OpenAPI 3.x first.

Is calling a tool over MCP slower than calling the API directly?

Yes, slightly. An MCP tool call adds a network hop, and the model spends tokens reading the tool's definition and result, so MCP is not about speed. What it buys instead is a model that can use an API across any MCP-speaking host without custom integration code and without the API credential ever appearing in the model's context.

What transport does MCP use: stdio or HTTP?

Both, depending on where the server runs. Local MCP servers typically use stdio, standard input and output between processes on the same machine. Remote servers use Streamable HTTP, which has replaced the older HTTP+SSE transport that specification revision 2026-07-28 now classifies as Deprecated.

Compare the MCP servers built around OpenAPI and other sources on AI Agents Listing.