Optimizing your OpenAPI document for MCP servers

If you’re building an AI-driven application, you’re probably exploring ways to connect it to your APIs.

Model Context Protocol (MCP)  servers are a powerful way to bridge AI models like Claude directly with your API endpoints. Using your OpenAPI document, Speakeasy automatically generates MCP servers alongside your SDK, allowing AI agents to refer to and use your API in a natural, conversational way.

In this guide, we’ll use an example mock racing lap API to demonstrate how to optimize an OpenAPI document for MCP server generation. The example API tracks drivers’ lap times across various racing circuits, allowing you to monitor and analyze driver performance. You can follow along with this guide using the example repository on GitHub .

We’ll look at how to improve your OpenAPI document – including optimizing descriptions, parameters, and naming conventions and using Speakeasy’s extensions – so that AI tools like Claude and Cursor can effortlessly interact with your API using the Speakeasy-generated MCP server.

What is MCP?

MCP is an open standard introduced by Anthropic  that enables AI agents to interact with APIs. Think of it as a translator for APIs, helping AI models interpret your API’s capabilities and interact with them in a consistent way. If SDKs are the bridge between your API and developers, MCP is the bridge between your API and AI agents.

Instead of building multiple custom integrations, developers can use a single MCP server to allow AI agents to interact with their API.

Where does OpenAPI fit in?

Since MCP is built around APIs, Speakeasy can generate a fully functional MCP server from your OpenAPI document. This means that your API’s capabilities are immediately accessible to LLMs that support MCP.

How does Speakeasy generate an MCP server using OpenAPI?

Speakeasy extracts every detail from your OpenAPI document: endpoints, methods, parameters, responses, and descriptions. It then generates a set of MCP tools that represent each API operation, complete with type-safe arguments and return values.

These tools are designed to be easily consumed by AI models, providing them with the necessary context to understand how to interact with your API.

You can then give your AI tool access to the MCP server, and the available tools and their parameters.

When Speakeasy generates your TypeScript SDK from an OpenAPI document, it also creates a corresponding MCP server. This MCP server is a lightweight wrapper around the generated SDK, specifically optimized for AI agent interactions.

The MCP server directory structure looks like this:

Each file in the tools/ directory corresponds directly to an SDK method, providing AI agents with clearly defined and type-safe tools. These tools describe the API operation, specify required arguments, handle execution through the SDK, and format the responses appropriately.

Here’s an example tool generated from the OpenAPI document for creating a new lap record. Notice how it implements the lapsCreateLap function from the SDK:

Since each MCP tool mirrors your SDK’s Zod schemas and method signatures, AI models like Claude can interact intuitively and accurately with your API as if they were using a native SDK. This means that the AI can understand the expected input and output types, making it easier to generate valid API calls.

To learn more about how Speakeasy generates MCP servers, check out our MCP release article.

See it in action: Racing-lap counter API

For example, here’s a snippet of the OpenAPI document for the /drivers/{driver_id}/laps/{lap_id} endpoint, along with the generated MCP tool:

This MCP tool is generated directly from the OpenAPI document, and it provides a clear description of what the endpoint does and detailed parameter information. An MCP-compatible LLM can use this information to understand how to call the API and what to expect in the response.

Natural language becomes API calls

Let’s take a look at how this works in practice. Say a user asks, “What’s Lewis Hamilton’s fastest lap at Silverstone?” using Claude desktop.

Claude first uses the lapsListLaps tool to get a list of all laps for Lewis Hamilton. It then uses the lapsGetLap tool to get the fastest lap time at Silverstone.

This works well because the tools and questions are fairly straightforward, and Claude can figure out a step-by-step approach to get the answer. However, this is not always the case.

The problem: When LLMs hallucinate with poor OpenAPI documentation

Even the best AI models can confidently make things up when working with poorly documented APIs. This hallucination problem gets especially bad with MCP servers built from thin OpenAPI documents.

Suppose we ask a seemingly straightforward question like, “What was Lance Stroll’s fastest lap at Silverstone?”. Here’s what can happen with insufficient API documentation, especially problematic since Lance Stroll isn’t even in the database.

In this example, rather than returning an error or saying it doesn’t know, Claude uses the lapsPostLap tool to create a completely new (and fictional) lap record for Lance Stroll at Silverstone.

This happens because:

1. Endpoint purpose is unclear: Without explicit documentation about the purpose of each endpoint, the LLM can’t determine which tool to use and when.

2. Parameter documentation has gaps: Vague parameter descriptions may lead the LLM to misjudge expected formats and values, resulting in incorrect assumptions about a tool’s intended purpose.

3. Context is missing: Without examples of real response patterns, the AI can’t infer what expected data looks like, resulting in incorrect assumptions about the API’s behavior.

4. Error guidance is insufficient: Poor error documentation prevents the AI from recognizing when additional context or clarification is needed, leading to more hallucinations.

The good news? These problems can mostly be avoided by structuring your MCP tools well and following a few simple guidelines when writing your OpenAPI document.

How to optimize your OpenAPI document

Prompt engineering is most of the work when it comes to getting good results from AI models. Similarly, the clearer and more structured your OpenAPI documentation is, the more effectively AI tools will be able to understand and use your API.

Try these simple strategies to enhance your OpenAPI document and make it easier for AI models to interact with your API through MCP.

Optimize MCP tools with x-speakeasy-mcp

Speakeasy provides a dedicated OpenAPI extension specifically for customizing your MCP tools. The x-speakeasy-mcp extension gives you fine-grained control over how your API operations are presented to AI agents, allowing you to:

• Override tool names and descriptions
• Group related tools with scopes
• Control which tools are available in different contexts

Here’s how to use this extension:

Customize tool names and descriptions

While a good operationId is great for SDK generation, MCP tools sometimes benefit from more descriptive names:

The improved MCP tool name and description provide clearer guidance to AI agents about what the endpoint does and when to use it while preserving your API’s original structure.

Organize tools with scopes

Scopes allow you to tag operations and control which tools are available in different contexts. This is particularly valuable when you want to:

• Separate read and write operations
• Protect destructive operations from accidental use
• Group related operations by feature or sensitivity

Here’s how to implement scopes:

When starting your MCP server, you can specify which scopes to include:

If you’re using the Claude desktop app, you can also specify scopes in the config:

Apply scopes across multiple operations

To apply scopes consistently across many operations, you can use the global x-speakeasy-mcp extension:

This automatically applies scopes based on operation name patterns, saving you from manually tagging each endpoint.

Use descriptive operationId values

Every API operation should have a unique, descriptive operationId that clearly indicates its purpose:

This naming convention helps AI models accurately map natural language requests like, “What’s Hamilton’s fastest lap?” to the correct tool, since the operationId is used as the default tool name.

Explain the purpose of each operation

When using MCP, it’s essential to provide clear descriptions for each operation. This is especially important for AI models, as they rely on these descriptions to understand the purpose and expected behavior of each endpoint.

Add detailed parameter descriptions and examples

To make it easier for AI models to understand your MCP tools, provide detailed descriptions for each parameter. This includes specifying the expected format, constraints, and examples. This helps the LLM choose the right tools when it needs to follow a step-by-step approach to accomplish a task.

Add examples to responses

To improve the LLM’s understanding of your API’s responses, provide detailed descriptions, examples, and expected structures. This helps the LLM accurately interpret the data returned by your API.

Final thoughts

While this post focuses on optimizing your OpenAPI document for MCP servers, these techniques are also good practice for writing well-structured, high-quality, comprehensive OpenAPI documents with great developer experience, whether or not you’re using Speakeasy or MCP.

For more information on how to improve your OpenAPI document, check out our OpenAPI best practices guide.