Developers building AI agents keep running into the same question: if OpenAPI already describes APIs, why does MCP exist? They look similar on the surface. Both define how a client interacts with a service. Both use structured schemas. Both aim to reduce guesswork.

But they were built for fundamentally different consumers. OpenAPI was built for human developers reading documentation. MCP was built for AI agents discovering capabilities at runtime.

What OpenAPI Does

OpenAPI (formerly Swagger) is a specification for describing REST APIs. You write a YAML or JSON file that lists every endpoint, parameter, request body, and response schema. Tools generate documentation, client SDKs, and mock servers from that spec.

It solves a real problem: when your API has dozens of endpoints, OpenAPI gives developers a machine-readable map. They read the spec (or the generated docs), write integration code, and ship.

OpenAPI works well when:

  • A human developer is writing the integration code up front
  • The API surface is known before the client runs
  • You want generated SDKs, validation, and documentation from one source of truth
  • The interaction pattern is HTTP request/response

Millions of APIs have OpenAPI specs. It is the standard for describing web services.

What MCP Does Differently

MCP (Model Context Protocol) was designed for a different consumer: an AI agent that needs to figure out what it can do with a service while it is running.

Instead of a static spec file that a developer reads before writing code, MCP servers advertise their capabilities dynamically. When an agent connects to an MCP server, it asks: what tools do you have? What resources can I read? What prompts are available? The server responds with structured descriptions the agent can act on immediately.

Key differences from OpenAPI:

  • Runtime discovery vs. build-time documentation. An OpenAPI spec is read by a developer before deployment. An MCP server is queried by an agent during execution. The agent does not need pre-written integration code.
  • Three primitives vs. one. OpenAPI describes endpoints. MCP exposes tools (actions), resources (contextual data), and prompts (interaction templates). An agent gets richer interaction patterns out of the box.
  • Transport flexibility. OpenAPI assumes HTTP. MCP works over stdio (local processes), HTTP with SSE (remote servers), and streamable HTTP. Local tools and remote services use the same protocol.
  • Agent-native context. MCP was designed so that an LLM can read a tool description and decide whether and how to call it. The descriptions, parameter schemas, and return types are optimized for model consumption, not human reading.

A Concrete Example

Say you have a CRM service. With OpenAPI, you publish a spec: GET /contacts, POST /contacts, PUT /contacts/{id}, and so on. A developer reads this, writes a wrapper, and deploys it with their agent.

With MCP, you build an MCP server that exposes tools like search_contacts, create_contact, and update_deal_stage. When an agent connects, it sees these tools, reads their descriptions and schemas, and can call them directly. No pre-built wrapper. No developer writing glue code for each endpoint.

The agent asks the server what it can do. The server tells it. The agent acts.

When OpenAPI Still Wins

OpenAPI is not going away. It is better suited when:

  • You are building for human developers first. If your primary consumers are developers writing traditional applications, OpenAPI gives them docs, SDKs, and validation.
  • You need strict API governance. OpenAPI specs enforce contracts. Versioning, deprecation, and breaking change detection are mature.
  • The service is not agent-facing. If no AI agent will ever call your API directly, the added structure of MCP has no audience.
  • You want generated code. The OpenAPI toolchain (codegen, linting, testing) is decades ahead of MCP tooling.

When MCP Wins

MCP is the right choice when:

  • An AI agent is the primary consumer. If the thing calling your service is an LLM deciding what to do next, MCP gives it the information it needs in the format it expects.
  • You want plug-and-play composability. An agent can connect to ten MCP servers and gain ten sets of capabilities without anyone writing integration code for each one.
  • Context matters. MCP resources let servers push relevant context to agents. An OpenAPI endpoint just returns data when asked.
  • Local and remote tools need one protocol. A filesystem tool running locally and a cloud database running remotely both speak MCP. OpenAPI only covers HTTP services.

Can They Work Together?

Yes. Several MCP servers are thin wrappers around existing REST APIs that already have OpenAPI specs. The OpenAPI spec defines the API contract. The MCP server translates that contract into something an agent can discover and use at runtime.

Think of it this way: OpenAPI describes an API for developers to build against. MCP describes capabilities for agents to use directly. One does not replace the other. They serve different sides of the same service.

FAQ

Q: Can an AI agent just use an OpenAPI spec directly? A: Some agent frameworks parse OpenAPI specs and convert them to tool definitions. This works for simple APIs but loses the runtime discovery, resource context, and transport flexibility that MCP provides natively.

Q: Should I write an MCP server if I already have an OpenAPI spec? A: If AI agents are (or will be) a significant consumer of your service, yes. The MCP server can use your existing API under the hood. You are adding an agent-native interface, not rewriting the service.

Q: Is MCP replacing OpenAPI? A: No. They solve different problems for different consumers. OpenAPI will remain the standard for describing REST APIs to developers. MCP is emerging as the standard for exposing capabilities to AI agents. Most services will eventually have both.