Your OpenAPI Implementation is Not an MCP Server

I get this question a lot: "Can't we just wrap our existing API with OpenAPI spec and use it as MCP tools?" It's a tempting idea, but here's the thing — it's an overly simplistic way to think about MCPs. Let me explain why, and show you a better approach.

The problem with wrapping existing APIs

LLMs are amazing, but they have a critical weakness: they're terrible at choosing between a wide variety of options. If you give an LLM a tool for every API endpoint in your application, (unless your app is very simple) you're setting yourself up for trouble.

Here's why:

1. Unpredictable API calls: LLMs might make a mess of API calls, often in the wrong order or context.
2. Tool selection issues: The LLM might choose inappropriate tools for the task at hand.
3. Lack of workflow understanding: Complex tasks often require multiple API calls in a specific sequence, which LLMs might not grasp.

Let me give you a simple example. Imagine you're building a pizza ordering system. You tell the LLM, "I want to order a pizza," and it decides, "Oh, I need to create the pizza first, then place an order for it." But that's not how it works — you already have pizzas, and the user just needs to order an existing one!

A better approach: Intentional user experiences

So, what's the solution? We need to think about MCPs the same way we think about UI design. Here's the key:

Think of the LLM as a human assistant using your application. You wouldn't give a human user direct access to every API endpoint, right? Instead, you create intuitive UI elements that guide them through specific workflows.

Here's how to approach this:

1. Look at your existing UI: What buttons and forms do you have?
2. Identify key workflows: What series of actions do users typically perform?
3. Create MCP tools for these workflows: Each tool should encapsulate a complete user task.

For example, instead of separate tools for "select pizza," "add toppings," and "place order," you might have a single "order custom pizza" tool that handles the entire process.

Let's break this down with a few examples:

1. Simple cases: Sometimes, a tool will map directly to an API endpoint. "Delete order" or "update post" could be straightforward tools.
2. Complex workflows: For an online ticketing system, "purchase ticket" might involve reserving the ticket, adding user details, processing payment, and sending a confirmation — all in one tool.
3. User-centric actions: Instead of exposing "create user," "assign role," and "send welcome email" as separate tools, you might have a single "onboard new team member" tool that handles the entire process.

Focus on the user experience, not just the API

The key takeaway here is this: don't think about your API in terms of resources and CRUD operations when designing MCP tools. Instead, focus on the user experience and the tasks they want to accomplish.

By creating intentional, workflow-focused tools, you'll make it much easier for LLMs to assist users effectively. You'll reduce errors, improve predictability, and create a more intuitive AI experience overall.

Remember, the goal isn't to expose every bit of functionality as a separate tool. It's to create a smooth, intuitive experience for users interacting with your application through an AI interface. Good luck, and happy tool designing!