Generating Production-Ready MCP Servers from OpenAPI Specifications

speakeasy · Tech · 2025 · source Agentic: yes · promotional bias: med · source-backed · extracted with prompt 0.5.6 (schema v2)

Generated from extraction.json — do not edit by hand. Every claim cites verbatim source evidence; stated means the quote directly asserts the claim, implied means it supports it indirectly.

Problem

Domain: API-to-agent tool generation

Speakeasy needed to generate production-ready MCP servers from OpenAPI documents so AI agents could use existing APIs, while avoiding tool overload, bad tool descriptions, fragile complex payloads, unsafe capability exposure, and manual customizations that disappear when generated code is regenerated.

Constraints:

• MCP servers often expose one tool per API operation, which can overwhelm model context windows
• OpenAPI descriptions written for human documentation can be verbose, repetitive, or too vague for LLM tool selection
• agents struggle with complex JSON, streaming responses, binary files, metadata-heavy payloads, and nested envelopes
• MCP servers can expose sensitive or destructive API capabilities directly to clients
• manual edits to generated MCP server code would need to be repeated after every regeneration
• the generator has to preserve OpenAPI as a source of truth for SDKs and documentation as well as MCP servers

Architecture

Speakeasy extends its OpenAPI generator to produce MCP servers while moving agent-specific customization into three durable layers: the OpenAPI document where appropriate, generator behavior for common transformations, and custom function files or overlays for endpoint-specific control. The generated MCP server exposes pruned, well-described tools, transforms complex payloads into LLM-friendly formats, and enforces scopes server-side so agents receive a focused, safer capability surface.

Diagram confidence: explicit (topology described by the source).

flowchart LR
  openapi_document["OpenAPI document"] --> speakeasy_mcp_generator["Speakeasy MCP generator"]
  openapi_document --> overlay_document["Overlay document"]
  overlay_document --> speakeasy_mcp_generator
  x_speakeasy_mcp_annotations["x-speakeasy-mcp annotations"] --> speakeasy_mcp_generator
  speakeasy_mcp_generator --> generated_mcp_server["Generated MCP server"]
  speakeasy_mcp_generator --> custom_function_file["Custom function file"]
  custom_function_file --> generated_mcp_server
  response_transformation_layer["Response transformation layer"] --> generated_mcp_server
  response_transformation_layer --> ai_agent["AI agent"]
  scope_configuration["Scope configuration"] --> generated_mcp_server
  generated_mcp_server --> mcp_client["MCP client"]
  generated_mcp_server --> backend_api["Backend API"]
  mcp_client --> ai_agent
  ai_agent --> mcp_client

Components

Data flow

An OpenAPI document enters the Speakeasy generator, optionally augmented with x-speakeasy-mcp annotations or overlays. The generator prunes disabled endpoints, emits MCP tool names, schemas, descriptions, and scope metadata, and handles common data-shape conversions such as streaming and binary responses. Custom function files or SDK hooks refine behavior for endpoint-specific cases. The resulting MCP server exposes a controlled tool set to MCP clients and AI agents, which then call the underlying API through the generated server rather than directly through raw OpenAPI operations.

Why this architecture

Speakeasy keeps OpenAPI as the single source of truth while adding MCP-specific controls outside the generated server because generated artifacts must be safe to regenerate. Tool pruning, concise agent-facing descriptions, data transformations, and server-side scopes reduce the agent's decision space and risk surface before the LLM chooses a tool.

Models used: LLM agents · smaller models with shorter context windows

Scale

• Speakeasy says it has generated over 50 MCP servers for customers, with many already running in production.
  “So far, we’ve used it to generate over 50 MCP servers for customers, with many already running in production.”article, stated
• Large APIs can exceed 500 operations, creating an overwhelming tool surface if mapped one-to-one.
  “MCP servers tend to have as many tools as there are operations, which is problematic for APIs with more than 500 operations, like GitHub’s.”article, stated
• A 200-endpoint OpenAPI document can easily create roughly 200 MCP tools.
  “Let’s say you have 200 endpoints in your OpenAPI document. Generating an MCP server from this document will easily create around 200 tools.”article, stated
• Many users rely on multiple MCP servers and smaller models, increasing context-window pressure.
  “with many users relying on multiple MCP servers and smaller LLMs, it can fill the context window before the prompt is processed.”article, stated

Alternatives considered (roads not taken)

Generate one MCP tool for every OpenAPI operation

Rejected because: The resulting tool explosion overwhelms the LLM's context window and makes wrong tool selection more likely.

Manually edit the generated MCP server

Rejected because: Manual generated-server changes would have to be repeated after every regeneration, so Speakeasy moves customization to OpenAPI, generator, overlays, and custom files.

Use the same verbose OpenAPI descriptions for humans and LLM tool selection

Rejected because: Verbose descriptions consume tokens and repeated details add noise when all tool descriptions enter the context window together.

Rely on client-side toggles to hide risky or irrelevant tools

Rejected because: Client-specific toggling becomes unscalable across many tools, clients, and environments, so Speakeasy supports server-side scopes.

Pass complex API responses directly to the LLM

Rejected because: Agents struggle with streaming, binary, metadata-heavy, and deeply nested response formats, so Speakeasy transforms data first.

Patterns

tool-use-orchestration (agent tool surface)

Speakeasy turns OpenAPI operations into MCP tools for agents, then prunes, scopes, and describes those tools so models can choose useful API capabilities reliably.

structured-output-contract (schema-driven tool generation)

OpenAPI and MCP both use schemas to define request/response and tool contracts, letting generated MCP tools expose names, schemas, and descriptions to agents.

safety-policy-enforcement (server-side access control)

Speakeasy uses endpoint scopes such as read, write, or product so generated MCP servers expose only the permitted operations regardless of client UI behavior.

guardrails-io-filtering (tool pruning and response shaping)

The generator can disable irrelevant endpoints and transform complex API payloads before they reach the agent, reducing unsafe or confusing tool exposure.

Tradeoffs

Keep OpenAPI as the source of truth while adding MCP-specific customization layers.

Chose OpenAPI plus generator behavior, extensions, overlays, and custom function files over Editing generated MCP server code directly.

Rationale: This preserves regeneration while letting teams tailor tools for agents without compromising SDK and documentation generation.

Prune tool surfaces before generation.

Chose Disable non-useful or out-of-scope endpoints in OpenAPI/MCP metadata over Letting the agent see every operation.

Rationale: Pruning reduces context-window load and makes tool choice more reliable for the model.

Use server-side scopes for access control.

Chose Scope-based server configuration over Manual per-client tool toggling.

Rationale: Server scopes scale across clients and environments and avoid relying on a UI setting to hide dangerous operations.

Transform complex responses before they reach the agent.

Chose Generator and hook-based response simplification over Sending raw streams, binary files, envelopes, or nested JSON to the LLM.

Rationale: Agents expect simple JSON-like outputs, so generated transforms and hooks make tool outputs easier for LLMs to process reliably.

Use overlays when MCP-specific descriptions would pollute the base OpenAPI document.

Chose Separate overlay documents over Putting every agent-facing term directly into the source OpenAPI spec.

Rationale: Overlays allow MCP-specific edits while keeping the original API spec clean for documentation and SDK use.

Gotchas (what bit them)

Tool explosion overwhelms model context and decision-making.

Root cause: A one-operation-to-one-tool mapping can expose hundreds of tools, especially for large APIs.

Resolution: Prune the OpenAPI document, disable non-useful endpoints, and keep only genuinely useful capabilities for the MCP use case.

Descriptions optimized for API docs can harm LLM tool selection.

Root cause: Long repeated descriptions consume tokens, while short vague descriptions fail to distinguish similar endpoints.

Resolution: Use clear, concise MCP-specific descriptions through x-speakeasy-mcp annotations or overlays when the human-facing OpenAPI docs cannot be changed.

Complex API payloads are brittle model inputs.

Root cause: APIs may return streams, binary media, metadata, or nested envelopes that agents are not good at processing.

Resolution: The generator and SDK hooks transform responses, such as buffering streams, Base64-encoding media, or converting CSV data to JSON.

Exposing all API operations creates safety and privacy risk.

Root cause: An agent connected to an MCP server may be one tool call away from leaking sensitive data or modifying accounts unintentionally.

Resolution: Define scopes before generation so the server exposes only the operations allowed for a given runtime context.

Manual generated-code edits do not survive regeneration.

Root cause: MCP servers are generated artifacts, so direct edits become repeat work whenever the OpenAPI document or generator changes.

Resolution: Speakeasy moves customizations into the OpenAPI document, the generator, custom function files, and overlays.

Evaluation

The article does not describe a formal benchmark harness. Speakeasy bases the guidance on lessons from generating 50-plus production MCP servers and evaluates failure modes by whether agents can choose the right tools, stay within context, process responses, preserve customizations across regeneration, and avoid unsafe exposure.

Metrics: number of production MCP servers generated · tool count per API · context-window pressure · wrong-tool selection risk · hallucinated response risk · regeneration safety of customizations · scope-controlled tool exposure

Outcomes

• Speakeasy generated more than 50 MCP servers for customers, with many already in production.
• The generator supports endpoint disabling through x-speakeasy-mcp metadata.
• MCP-specific descriptions can live in extensions or overlays rather than direct generated-server edits.
• Complex response formats can be transformed before they reach the MCP client or LLM.
• Server-side scopes can restrict generated tool exposure independent of the client.

The production lessons come from more than 50 generated MCP servers. The article repeatedly frames scale around large APIs: 200 endpoints mapping to roughly 200 tools, APIs with more than 500 operations, multiple MCP servers, and smaller models with shorter context windows.