OpenAPI vs MCP and When You Need Both

You already have a REST API, an OpenAPI spec and a perfectly serviceable backend. Then someone says you need MCP for your AI agent, and suddenly the conversation sounds suspiciously like you are about to rebuild everything you already built.

Please do not start there.

OpenAPI describes how to call your HTTP API. The Model Context Protocol gives AI applications a common way to discover and use tools and contextual data. You can put an MCP server in front of an existing API while keeping the business logic, validation and data where they already belong.

The MCP vs OpenAPI question usually comes down to who needs access and how they will connect. Your frontend may need a generated API client. Your coding assistant may benefit from discovering a small set of tools. Both can use the same underlying service.

This guide explains the difference, how OpenAPI operations become MCP tools, and when the extra layer is worth running. My default would be to keep a good API contract, add MCP when a real client needs it, and write custom integration code only for behaviour that is actually custom. There is enough glue code in the world already.

OpenAPI vs MCP at a glance

These technologies describe different parts of an integration. OpenAPI is an interface description; MCP is a communication protocol with defined methods for discovering and using capabilities. Calling them two competing API formats loses the useful distinction immediately.

The important word in that table is compatible. MCP provides a standardized way to connect, but clients differ in the features, transports and authorization flows they support. A logo on an integration page is not a substitute for testing the client you intend to use.

What OpenAPI does for REST APIs

An OpenAPI document describes an HTTP API in JSON or YAML. It tells software and developers which endpoints exist, how to supply parameters and request bodies, which response schemas to expect, and how authentication is described.

For example, the contract for GET /tickets/{id} might define a required ticket ID, an authentication scheme and a ticket response object. Your application still implements the lookup and decides whether the caller may see that ticket.

The OpenAPI specification is intended for both humans and machines. It can support interactive documentation such as Swagger UI, generated SDKs, validation and automated testing. It is not limited to humans browsing documentation, and software does not have to wait for a developer to read the file before it can use it.

An OpenAPI schema may describe reusable objects under components.schemas, while paths holds operations and components.securitySchemes describes authentication mechanisms. An OpenAPI spec can be served at /openapi.json, but the filename and URL are conventions, not requirements.

Be precise about versions. JSON Schema compatibility varies across OpenAPI versions, and your converter or code generator may support a different version from the latest published standard. A newer document is only useful if the tools consuming it understand its structure.

What OpenAPI does not do is run the API. Writing “requires authentication” in a schema does not implement authentication, any more than documenting a refund endpoint refunds the money.

What the Model Context Protocol adds

The Model Context Protocol defines how an AI application connects to servers offering tools and context. Large language models do not usually open these connections themselves. The host application manages them and decides what capabilities and results reach the model.

In MCP terminology, the host is the application, an MCP client is a connector within it, and an MCP server provides capabilities. A host can manage multiple clients connected to different servers. That distinction matters when you are debugging permissions or deciding which component actually sent a request.

The MCP protocol uses JSON-RPC messages. Standard transport options include stdio for a client-launched local process and Streamable HTTP for remote communication. Streamable HTTP can use SSE to stream a response; that does not make every older SSE integration interchangeable with a current server. Check the protocol version and transport supported at both ends.

MCP gives the client defined ways to discover available tools and invoke them. It does not supply the reasoning that chooses the right tool, and it does not make an ambiguous description reliable by putting it in a standard envelope.

The client still needs a sensible interface. A tool called execute_operation with a large free-form JSON parameter is technically an interface. So is a door with no handle. Neither is especially considerate.

How MCP tools differ from resources and prompts

The three server features have different jobs. You do not have to implement all of them to create a useful MCP server.

Tools expose callable operations. A client can request the tool list and submit a call with structured arguments. The implementation might read a ticket, post a comment or run a calculation. Tools can read data as well as change it.

MCP resources expose contextual data identified by a URI. A resource might contain a document, a database schema or a customer summary. A resource template such as customer://{id} describes a parameterized address. The host decides how to retrieve and include that context; the URI does not automatically give the model database access. The resource specification explains that application-controlled role.

Prompts provide reusable message templates that a client can retrieve and present through its interface. A prompt can guide a task, but it is not an orchestration engine. Defining a “refund customer” prompt does not implement the refund transaction or its failure handling.

Likewise, an agent's skills or instructions can teach it how to approach a workflow, but they do not replace the connection, credentials or code needed to execute it. Keep those responsibilities clear and you spend less time wondering which layer is supposed to do the actual work.

The difference is not simple APIs versus clever workflows

An MCP tool can wrap several API calls, but an HTTP endpoint can do that too. You can implement POST /refunds as a business operation that checks an order, records a refund and updates an internal system. OpenAPI can describe that endpoint perfectly well.

Neither OpenAPI nor MCP implements the workflow by itself. Your backend, server or orchestration layer does.

The useful design decision is where the operation belongs. If several applications need the same refund rules, those rules probably belong in a shared service. If the agent needs a different presentation of an existing capability, an MCP adapter may be enough.

MCP is also not required for every AI integration. An AI application can call an API through a custom integration or another tool-calling mechanism. MCP becomes valuable when a shared client-server interface removes integration work across the applications you actually use.

If you need to build that adapter manually, my guide to building an MCP server for an existing API covers the implementation path. Keep the custom code for transformations, policy or multi-system logic that generation cannot reasonably infer.

How an MCP server uses an OpenAPI spec

An OpenAPI-to-MCP converter reads the API contract and generates tool definitions plus the mapping needed to call the API. That mapping is converter behaviour, not a rule requiring every MCP server to read OpenAPI.

For a support API, you might deliberately expose three operations:

• GET /tickets/{id} becomes get_ticket.

• POST /tickets/{id}/comments becomes add_ticket_comment.

• PATCH /tickets/{id} becomes a constrained update_ticket_status tool.

That last mapping needs attention. A PATCH operation that accepts twenty editable fields does not automatically become a status-only tool because somebody gave it a nicer name. Restrict the accepted fields and the execution mapping if status changes are all the agent should perform.

A converter may use operationId for the tool name, combine summaries and descriptions, and translate parameters plus request bodies into the input schema. Responses can inform the output schema and returned content. Exact behaviour depends on the converter, supported OpenAPI specifications and schema features.

The MCP client calls the generated tool. The server translates that into the appropriate HTTP request, applies upstream authentication, calls the service and returns a result. The agent does not need to construct the URL or remember which field belongs in the query string.

For the practical setup, the OpenAPI to MCP guide walks through generated tools, testing and the local versus hosted choices.

Good OpenAPI JSON makes better tools

Conversion reuses the contract you supply. It cannot reliably recover business meaning that never appeared in the contract.

I would review these before blaming the AI assistant:

• Use stable, descriptive operation IDs. get_ticket says more than ticketsControllerFindOne.

• Explain required parameters, valid enums, formats and request body constraints.

• Describe response schemas and expected errors, including empty results and missing records.

• Make side effects explicit. A tool that sends a notification should not sound like a harmless preview.

• Check references, authentication requirements and the actual API behaviour against the OpenAPI document.

A JSON Schema default is not a promise that your converter, validator or backend will insert a value. Confirm the behaviour rather than letting three layers make three different assumptions about the same missing parameter.

You also need to curate the available tools. A 300-operation admin API does not necessarily belong in every agent context. Start with the operations required for one task and expand when there is a reason.

Some clients and servers support ways to discover or load definitions selectively. Test what yours actually sends to the model. A catalog being discoverable at runtime does not guarantee that exposing an enormous catalog is cheap or useful.

When OpenAPI alone is enough

If your browser frontend uses a generated TypeScript client, your partner calls documented REST endpoints, or two services exchange known HTTP requests, OpenAPI may already do everything you need.

Even an AI feature may not need MCP. If you control one application making a handful of fixed calls, a direct API integration may be simpler to operate and easier to test. The existence of an agent does not create a legal obligation to install another server.

You can also use an OpenAPI document to help a coding assistant create integration code. That development task does not automatically require a production MCP deployment.

Keep the contract accurate either way. It remains useful for client generation, testing and future integrations. Choosing not to add MCP today does not mean abandoning machine-readable API documentation.

When MCP adds enough value to justify the extra layer

MCP is useful when compatible AI clients need a consistent way to discover and call your capabilities. You might expose a support API to a coding assistant and an internal agent without building a separate adapter inside each host.

It also helps when the capability is not naturally a REST API. An MCP server can wrap local code, files or database access. It does not require an OpenAPI spec underneath it.

For example, an assistant could directly query a customer summary through an approved tool, retrieve a policy resource and propose an account update. The application still decides which capabilities to expose, what the user has authorized and whether an action needs confirmation.

Check the actual client experience before committing to the architecture. Can your intended version of Cursor or another host connect through the chosen transport? Does it support the resources you need? How does it handle authentication, errors and tool approvals?

If the service has to stay inside your network, the self-hosted MCP server guide covers local and internal API access. Remote convenience should not quietly become permission to expose your internal stack to the internet.

Security and debugging still need engineering

OpenAPI can describe security schemes, while the API implementation enforces them. MCP has an HTTP authorization framework, but connecting successfully is not permission to invoke every operation or read every customer's data. The MCP authorization specification defines that transport-level framework.

Keep the client credential accepted by the MCP endpoint separate from the upstream API credential. Enforce tool and resource permissions at execution time. Hiding a destructive tool from the list does not protect it if another caller can still invoke it by name.

Tool annotations can describe properties such as read-only behaviour or destructive effects. Treat them as hints for clients, not access controls. Marking an operation read-only cannot stop a backend from making a change.

For debugging, follow the whole request: which client called which tool, which arguments passed validation, which API operation ran and what response came back. Redact secrets and sensitive fields before storing traces. A single “tool failed” message is a very efficient way to lose an afternoon.

The MCP gateway architecture guide explains where centralized routing, access policy and logging can help once several clients and servers are involved. You still need the underlying API to enforce its own rules.

A sensible way to use both in production

I would start with one real user task and the smallest set of operations needed to complete it. “Expose our entire platform to agents” is an ambition, not a useful first test.

First, verify the OpenAPI contract against the live API. Then generate or implement the MCP tools for that task. Review their names, inputs, returned fields and side effects before connecting a model.

Test the calls directly, then test them through the client. Include invalid parameters, missing records, unauthorized access, retries and upstream failures. A working list-tools response proves that discovery works. It tells you considerably less about whether a failed write can be retried safely.

Add composite operations where they simplify a real workflow. Decide what happens when step two fails after step one succeeds. MCP does not provide transaction rollback just because the diagram has one tool box instead of three API boxes.

Version the contract and generated tool definitions together where appropriate. Run compatibility checks when either changes. You do not need to fine-tune a model to use MCP; you do need to refine tool descriptions, validate behaviour and maintain the integration.

This is how the two layers stay useful: OpenAPI keeps the HTTP contract explicit, and MCP provides the client-facing capability interface. Your tests keep both honest.

Where Fetch Hive fits

Fetch Hive's MCP Gateway takes an OpenAPI 3.0 or 3.1 spec in JSON or YAML and compiles it into MCP tools. That supported input range matters even though the OpenAPI standard has newer releases. Check your document version before pointing a converter at it.

The open-source CLI is available on GitHub and can run locally or self-hosted. The hosted option adds a managed endpoint with access tokens, rate limits, quotas, tool policy, request logs and a playground. You can review a spec through the free readiness report before deciding how to deploy it.

Use generation to remove repetitive mapping work, then inspect the result. Fix unclear operations in the source contract where possible, configure the tool surface deliberately, and reserve custom code for the parts that need custom behaviour.

If you already have the API, start with the OpenAPI to MCP walkthrough. There is very little value in manually copying a good schema into another set of decorators purely to prove you can.

The takeaway

OpenAPI and MCP can share the same backend without fighting over who owns it. OpenAPI describes the HTTP interface. MCP gives compatible AI applications a protocol for discovering tools and accessing context.

Use OpenAPI alone when it covers the consumers you have. Add MCP when client compatibility, reusable tool access or contextual resources justify the extra layer. Use both when the API serves conventional applications and AI agents.

Start with a useful operation, a clear schema and a test that proves it behaves correctly. That will get you further than declaring one standard dead because the other one had a good week on LinkedIn.