Stop Converting OpenAPI Specs Into MCP Servers

MCP has quickly become the standard for connecting agents to data, and as a result new MCP servers are popping up everywhere. Looking online, you can find tens of thousands of MCP servers, and most of these are AI-generated or auto-converted straight from existing OpenAPI specs.

And that’s not surprising, as the majority of APIs built by developers are RESTful-ish, and OpenAPI is the dominant way to describe them. So when developers first try out MCP, the obvious move is to point at an OpenAPI spec file and turn every endpoint into a collection of tools.

But when you do that, you miss the whole point of MCP. Instead of creating better tools for agents, you just increase the risk of hallucinations and poor fault tolerance.

In this post, I’ll walk through some of the frustrations I’ve seen firsthand and explain why treating MCP like just another API spec doesn’t work.

Too many tools fill up the context window quickly

Most MCP servers today are used for tool calling. But that doesn’t mean they should expose hundreds of low-level API endpoints. An MCP server is a set of tools, prompts, and resources that each should represent something an agent can actually use.

The most common mistake I see is developers auto-converting OpenAPI specs into MCP servers without any curation. That usually produces dozens (or even hundreds) of very low-level tools, one for every single endpoint.

In theory, this might look powerful. In practice, it causes problems. The LLMs the agent will connect to have a limited context window, and every tool definition takes up space in that window. Too many tools lead to confusion, poor fault tolerance, and a higher risk of hallucinations.

Curation helps. By exposing only the endpoints that matter, you keep your MCP server focused and more reliable. Some clients like Cursor or Claude Desktop let users toggle tools on and off, but not every environment works that way. If someone connects directly from code, they’d have to curate the tools themselves if you haven’t already done it for them.

Agents are bad at taking multi-step actions

A good MCP server should feel like a well-designed API. One of the biggest problems with exposing every endpoint as a tool is that you push the complexity of multi-step actions onto the agent.

Take this example: “refund a customer by email.”

With a 1:1 OpenAPI conversion, the agent has to:

• Call get_customers with an email address to get the customer ID.
• Call get_customer_orders to fetch their orders.
• Call create_refund with the right order ID.

That’s three separate steps, and a lot can go wrong in the middle. The agent might pass the wrong email, pick the wrong order, or start calling tools like get_customer_by_id or get_order_by_id to collect information it doesn't need to get the job done. LLMs aren’t good at following exact step-by-step flows in a reliable, deterministic way.

If you design the MCP server directly, instead of just converting the OpenAPI spec, you can collapse this workflow into a single action. That makes the process deterministic, reduces hallucinations, and improves fault tolerance.

There are two ways to handle multi-step actions in MCP: prompts or better tool design.

MCP servers can return prompts that could help the agent create a plan on which tools to call, and in what order. In this example, a prompt might spell out the steps for refunding a customer by email. That’s better than leaving the agent to figure it out, but still error-prone.

The stronger approach is to design a higher-level tool that handles the entire workflow behind the scenes. The agent just calls refund_customer_by_email, and your server does the rest. That’s the kind of deterministic design that makes MCP servers actually usable.

Layered Tool Design can help

Another way to keep MCP servers that need to span a lot of tools usable is to design them in layers.

Block’s engineering team (the company behind Square) introduced this layered pattern with their own Square MCP server, and it’s a good example of how to structure tools so agents don’t get overwhelmed.

The idea is simple:

• Discovery tools help the agent understand what’s available.
• Planning tools guide it toward the right action.
• Execution tools perform the actual operation.

This layered approach makes servers easier to use and more fault tolerant. Instead of giving the agent a flat list of dozens of low-level tools, you organize them into progressive steps. The agent can start broad, narrow down, and then execute without getting lost in irrelevant options.

You don’t have to build this from scratch either. With libraries like mcp-composer, you can implement the layered tool pattern on top of existing OpenAPI specs. The documentation explains how to set up this pattern in a couple of steps, including how to add other capabilities like authentication to MCP servers (more about that in a later blog post).

The result is an MCP server that agents can reliably work with, one that is deterministic, less prone to hallucinations, and easier for users to understand.

Other Considerations

There are a few other points worth keeping in mind when building MCP servers based on your OpenAPI specification.

⚠️ Error messages: OpenAPI responses aren’t written for LLMs. A "404 not found" might make sense to a developer, but for an agent it’s ambiguous. Was the email wrong? The order missing? Or is the whole service unavailable? Consider normalizing errors into responses the agent can reason about.

⚠️ Irrevocable actions: Just because your API has a DELETE /orders endpoint doesn’t mean it should be exposed as an MCP tool. Agents don’t always understand the consequences of destructive actions. Ask yourself: should this action really be available to the agent, and is there a human in the loop to mitigate?

⚠️ Authentication: We didn’t even touch on auth and security in this post, but they’re critical pieces. From bearer tokens to OAuth delegation, authentication and authorization add another layer of complexity you’ll need to design for. I recommend reading the article The “S” in MCP Stands for Security to learn more about this topic.

These aren’t reasons to avoid MCP. They’re reminders that building good MCP servers means designing for agents, not just translating existing APIs.

If you found this tutorial helpful, don’t forget to share it with your network. For more content on AI and web development, subscribe to my YouTube channel and connect with me on LinkedIn, X, or Bluesky.