OpenAPI & REST APIs vs Model Context Protocol (MCP)
OpenAPI 3.1 & bespoke REST APIs is the classic web primitive built for human browsers and pre-integrated services (Describe HTTP endpoints, request parameters, and response schemas for human developers and SDK code generators), whereas Model Context Protocol (MCP) and its step 5 (Act) peers provide the machine-native agentic surface (GET {endpoint}/server-card (SEP-2127 Final, application/mcp-server-card+json, discovered via /.well-known/ai-catalog.json; /.well-known/mcp.json is legacy SEP-1649)) so autonomous agents can answer: "How does an AI application call tools and pull structured context, prompts, and data from an external server?" Across the agenticweb.wiki conformance panel, Model Context Protocol is multi-implementation (19 of 19 probed origins (last checked 2026-10-23)).
How OpenAPI & REST APIs compares to Model Context Protocol (MCP) at step 5 (Act): why the classic primitive breaks for software agents, and how sites deploy both together.
| Dimension | OpenAPI 3.1 & bespoke REST APIs Classic web | Model Context Protocol MCP Agentic web |
|---|---|---|
| Primary consumer | Human driving a web browser or pre-integrated developer code | Autonomous software agent, coding harness, or AI search/RAG crawler |
| Lifecycle step | Classic web baseline for step 5 (Act) | 5 Act: Do something for me |
| Core question answered | Describe HTTP endpoints, request parameters, and response schemas for human developers and SDK code generators. | How does an AI application call tools and pull structured context, prompts, and data from an external server? |
| Wire format & entrypoint | /openapi.json or /.well-known/api-catalog (RFC 9727) | endpoint at GET {endpoint}/server-card (SEP-2127 Final, application/mcp-server-card+json, discovered via /.well-known/ai-catalog.json; /.well-known/mcp.json is legacy SEP-1649) |
| Failure mode for agents | OpenAPI documents frequently list hundreds of low-level CRUD routes that exceed an LLM's context window, lack stateful session negotiation or prompt/resource primitives, and require custom per-service authentication glue before an agent can execute a multi-step workflow. | Solved natively: The Model Context Protocol (MCP) is a JSON-RPC 2.0 based protocol that lets an AI "host" application (an IDE, a chat client) connect, through a "client" it embeds, to one or more "servers" that expose tools (functions the model can call), resources (data or content), and prompts (reusable templates). |
| Governance & status | Established IETF / W3C / industry baseline | Agentic AI Foundation (Linux Foundation umbrella); day-to-day spec work in the modelcontextprotocol GitHub org via public SEPs (Specification Enhancement Proposals) and working groups — Active open specification, current dated release 2026-07-28 |
| Live adoption (/check/ census) | Universal across the classic web | multi-implementation — 19 of 19 probed origins (last checked 2026-10-23) |
| Primary specification | https://spec.openapis.org/oas/v3.1.0.html | https://modelcontextprotocol.io/specification/2026-07-28/index |
Why OpenAPI & REST APIs breaks when the caller is an agent
OpenAPI documents frequently list hundreds of low-level CRUD routes that exceed an LLM's context window, lack stateful session negotiation or prompt/resource primitives, and require custom per-service authentication glue before an agent can execute a multi-step workflow.
When to use which (and how they work together)
- Keep OpenAPI 3.1 & bespoke REST APIs: You are publishing HTTP microservices for human developers, typed SDK generators, API gateways, or deterministic service-to-service integrations.
- Add Model Context Protocol (MCP): You want AI coding harnesses (Claude Code, Cursor, VS Code, Zed) and autonomous agents to discover and invoke curated, task-level tools, prompts, and context resources over a single stateful or stateless JSON-RPC transport.
All agentic web standards replacing or extending OpenAPI & REST APIs
- Model Context Protocol (MCP) — multi-implementation · 19/19 probed origins: How does an AI application call tools and pull structured context, prompts, and data from an external server?
- MCP Server Cards (SEP-2127) — multi-implementation · 19/19 probed origins: How can a client learn what an MCP server offers before connecting to it?
- api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs (RFC 9727) — multi-implementation · 93/574 probed origins: Given a publisher's domain, where is the machine-readable list of the APIs it exposes?
- Agent Skills — multi-implementation · 83/572 probed origins: How can reusable, on-demand procedural instructions and bundled resources be packaged so any compatible agent can load and run them?
- WebMCP — prototype: What JavaScript tools can a web page register so an in-browser AI agent can call them directly instead of scraping the DOM?
- NLWeb — prototype: How can a site expose a natural-language question-answering interface grounded in its own Schema.org-structured content, for both humans and agents?