Generate MCP servers from OpenAPI documents

Learn how to build MCP servers from your OpenAPI documents using Speakeasy for production-ready servers with extensive customization options.

Getting started with Speakeasy

Use the following steps to build an MCP server using Speakeasy.

Install the Speakeasy CLI with the following commands:


# Homebrew (macOS)
brew install speakeasy-api/tap/speakeasy
 
# Script Installation (macOS and Linux)
curl -fsSL https://go.speakeasy.com/cli-install.sh | sh

Run the Speakeasy quickstart command:
```
speakeasy quickstart --mcp
```
Indicate whether you plan to deploy your server on Cloudflare.

Cloudflare is a popular choice for hosting MCP servers. If selected, a Cloudflare Worker config file is generated with your MCP server code, making it easy to deploy your server to a Cloudflare Worker.

These steps create a TypeScript-based MCP server in the specified directory, ready to be deployed into production.

Example server code

The generated MCP server includes a comprehensive file structure with TypeScript source code:

- core.ts
- - build.mts
  - cli.ts
  - console-logger.ts
  - extensions.ts
  - mcp-server.ts
  - prompts.ts
  - resources.ts
  - scopes.ts
  - server.ts
  - shared.ts
  - tools.ts

Running your MCP server locally

You can run your MCP server from the generated code, a published npm package, or the generated MCP Bundle (MCPB) package.

Local development setup

For local development and debugging, you can run your MCP server directly from the generated code:


{
  "mcpServers": {
    "MyAPI": {
      "command": "node",
      "args": ["/path/to/repo/bin/mcp-server.js", "start"],
      "env": {
        "API_TOKEN": "your-api-token-here"
      }
    }
  }
}

This configuration allows you to do the following:

Debug your server code directly.
Make real-time changes during development.
Test API integrations locally.
Validate tool functionality before distribution.

Testing with a published package

Once you’ve published your MCP server to npm (following our SDK publishing guide), you can test using the npm package format that will be used in production:


{
  "mcpServers": {
    "MyAPI": {
      "command": "npx",
      "args": ["your-npm-package@latest", "start"],
      "env": {
        "API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Note: You must first publish your package to npm before you can test it using this configuration.

Using the generated MCPB

For the most user-friendly testing experience, use the generated MCPB package. Claude Desktop and other MCP clients can load MCPB files directly:

Locate your generated MCPB file in the output directory (it typically has a .mcpb extension).
Install the MCPB in your MCP client following the client’s installation process.
Configure environment variables if your server requires authentication.

Advanced configuration

You can further configure your MCP server to specify the tools or tool scopes it includes at runtime.

Specify scopes at runtime

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


{
  "mcpServers": {
    "MyAPI": {
      "command": "npx",
      "args": ["your-npm-package@latest", "start", "--scope", "read"],
      "env": {
        "API_TOKEN": "your-api-token-here"
      }
    }
  }
}

This example configuration only mounts tools tagged with the read scope, creating a read-only server.

Specify individual tools

You can further limit the subset of tools mounted on an MCP server by specifying individual tool names:


{
  "mcpServers": {
    "MyAPI": {
      "command": "npx",
      "args": ["your-npm-package@latest", "start", "--tool", "my_tool_1", "--tool", "my_tool_2"],
      "env": {
        "API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Progressive discovery with dynamic mode

MCP servers with many tools can bloat LLM context windows, leading to increased token usage and tool confusion. Dynamic mode solves this by exposing only a small set of meta-tools that let agents progressively discover and invoke tools on demand.

To enable dynamic mode, pass the --mode dynamic flag when starting your server:


{
  "mcpServers": {
    "MyAPI": {
      "command": "npx",
      "args": ["your-npm-package@latest", "start", "--mode", "dynamic"],
      "env": {
        "API_TOKEN": "your-api-token-here"
      }
    }
  }
}

In dynamic mode, the server registers only the following meta-tools instead of every individual tool:

list_tools: Lists all available tools with their names and descriptions.
describe_tool: Returns the input schema for one or more tools by name.
execute_tool: Executes a tool by name with the provided input parameters.
list_scopes: Lists the scopes available on the server. Only registered if the server has scopes defined.

This approach significantly reduces the number of tokens sent to the LLM on each request, which is especially useful for servers with a large number of tools.

You can combine dynamic mode with scope and tool filters:


{
  "mcpServers": {
    "MyAPI": {
      "command": "npx",
      "args": ["your-npm-package@latest", "start", "--mode", "dynamic", "--scope", "read"],
      "env": {
        "API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Distribution and hosting options

Speakeasy generates MCP servers with three primary distribution methods. You can distribute your server as an npm package, a Cloudflare Worker, or an MCPB file. These methods aren’t mutually exclusive — most customers use all three approaches to serve different use cases.

Distribute your MCP server on npm

Publishing your MCP server as an npm package is the most common starting point, as it provides the most flexible distribution method, in addition to the following benefits:

Universal compatibility: You can use a single command that works with all major MCP clients.
Easy customization: Users can modify tools, add tools, and extend functionality.
Version management: Standard npm versioning and dependency management apply.
Team sharing: Distribution across development teams is simple.


{
  "mcpServers": {
    "MyAPI": {
      "command": "npx",
      "args": ["your-npm-package@latest", "start"],
      "env": {
        "API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Follow the SDK publishing guide for detailed instructions on publishing to npm and other package managers.

Deploy your MCP server to Cloudflare Workers

Cloudflare hosting enables OAuth authentication flows and eliminates the need for users to manage API keys directly. The benefits include:

OAuth support: End-users authenticate through OAuth instead of providing API keys.
Serverless hosting: No infrastructure management is required.
Global distribution: You can use Cloudflare’s edge network for low latency.
Same customization: Full tool customization capabilities are available.

Follow the Cloudflare deployment guide for detailed instructions on using Cloudflare hosting.

Generate your MCP server as an MCPB file

In addition to a drag-and-drop experience for end users (particularly in Claude Desktop), MCPB provides the following benefits:

User-friendly installation: Drag-and-drop installation in Claude Desktop.
Guided setup: Nicely prompts end-users for API keys and auth credentials.
Self-contained format: All dependencies and metadata bundled together.
Cross-platform compatibility: Works across different operating systems and MCP clients.

Speakeasy automatically generates MCP Bundle (.mcpb files) as part of MCP server generation. The MCPB includes:

A manifest.json file, containing metadata describing your MCP server
All the necessary server files, packaged for distribution
Tool descriptions and parameters, automatically inferred from your OpenAPI document
Icon and branding assets, if provided

You can customize the generated MCPB manifest through the gen.yaml configuration file:


targets:
  mcp-typescript:
    mcpbManifestOverlay:
      icon: "https://example.com/my-icon.png"
      displayName: "My Custom API Tools"
      description: "Custom description for my MCP server"
      version: "1.0.0"

Hybrid distribution strategy

You can use all three distribution methods simultaneously, giving users the flexibility to choose their preferred installation method based on their specific needs and technical requirements.

Response validation

By default, Speakeasy-generated MCP servers skip structured deserialization and Zod validation on HTTP responses. Instead, the raw response data is passed through directly as MCP tool results. This default behavior provides forward compatibility, allowing MCP tool calls to return data even if the API response doesn’t perfectly match the OpenAPI JSON Schema.

You can control this behavior using the validateResponse flag in gen.yaml:


mcp-typescript:
  validateResponse: false

When validateResponse is set to false (the default for new servers), no Zod schema validation is performed on HTTP response data. The raw data is passed through as MCP tool results, with minimal processing such as base64 encoding for binary image and audio data.

When validateResponse is set to true, HTTP responses are validated using generated Zod schemas before being returned as tool results. This provides strict type checking but may cause tool calls to fail if the API response contains fields or values that don’t conform to the OpenAPI specification.

Disabling validation is useful when:

The API may return additional fields not described in the OpenAPI specification.
There is little value in blocking LLM agents from reading data that may have minor schema inconsistencies.
You want to maximize the reliability of your MCP server by allowing it to handle API evolution gracefully.

For more details on this and other MCP server configuration options, see the MCP server configuration reference.

Best practices

When building MCP servers with Speakeasy:

Use clear OpenAPI documentation: Well-documented APIs generate better MCP tools.
Implement proper error handling: Ensure your API returns meaningful error messages.
Use the x-speakeasy-mcp extension: Customize tool names, descriptions, and scopes.
Test thoroughly: Verify that your MCP server works with different clients.
Version your APIs: Use semantic versioning for your OpenAPI documents.
Monitor performance: Track the usage and performance of your MCP tools.
Provide clear branding: Include a .png icon file in your project for automatic MCPB icon detection.
Customize MCPB metadata: Use mcpbManifestOverlay in gen.yaml to provide custom display names and descriptions.

Next steps

Having set up your MCP server with Speakeasy, you can now learn to do the following:

Customize your MCP tools: Customize your generated tools using the x-speakeasy-mcp OpenAPI extension.
Build custom resources: Add custom tools and resources to your MCP server
Use custom prompts: Create reusable prompt templates.
Set up OAuth: Configure authentication for your MCP server.

Last updated on January 22, 2026