Architecture
OpenAPI (Swagger) describes an API for developers. MCP describes tools for a model. They are layers, not rivals, and the choice shows up in discovery, security and long tasks.
6 Nov 2026 · 6 min read
Most companies already have APIs, documented in OpenAPI, the specification behind Swagger. The question for an agent project is whether to wire the agent to those APIs by hand or to put an MCP server in front of them. The honest answer is that it is not either-or: an MCP server very often wraps the same REST API.
The OpenAPI Specification describes HTTP APIs: paths, parameters, request and response bodies. Version 3.1 defines its Schema Object as a superset of JSON Schema draft 2020-12. Its reader is a developer or a code generator at build time.
The Model Context Protocol is built for a different reader: the model, at run time. Messages are JSON-RPC. A client sends a tools/list request to discover the tools a server offers, and the server must answer with the set currently available to that client. A server can also notify the client that its list of tools has changed.
Neither design gives you security for free. The MCP specification says that, for trust and safety, there should always be a human in the loop with the ability to deny tool invocations, and its HTTP authorization is based on OAuth 2.1. Scopes, limits, approvals and audit still have to be built, and they should live outside the model.
A task that takes minutes should not hold a connection open. HTTP's 202 Accepted means the request was accepted for processing but processing has not completed. Return it with a job identifier, let the client poll, and describe the events behind it, for example with AsyncAPI. The second tab above shows that flow.
Tell us about one process. We'll show you how an agent could handle it, and what to measure to know it's working.