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 Desktop Extensions (DXT) 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 DXT

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

Locate your generated DXT file in the output directory (it typically has a .dxt extension).
Install the DXT 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"
      }
    }
  }
}

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 a DXT 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 a DXT file

In addition to a drag-and-drop experience for end users (particularly in Claude Desktop), DXT 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 Anthropic Desktop Extensions (.dxt files) as part of MCP server generation. The DXT 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 DXT manifest through the gen.yaml configuration file:


targets:
  mcp-typescript:
    dxtManifestOverlay:
      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.

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 DXT icon detection.
Customize DXT metadata: Use dxtManifestOverlay 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 September 16, 2025