Generate MCP Servers from OpenAPI/Swagger

Speakeasy can generate Model Context Protocol (MCP) servers from your OpenAPI specification, enabling integration with AI agents and tools that support MCP.

What is Model Context Protocol?

Model Context Protocol  (MCP) is an open source protocol developed by Anthropic for defining tools which is beginning to be adopted by many AI agent platforms like the Claude  desktop app or Cursor  code editor. The full list of clients is available here .

TypeScript SDKs generated with Speakeasy can include a Model Context Protocol (MCP) server which allows them to be integrated with any supported MCP client.

Getting Started

Follow these steps to generate an MCP server from your OpenAPI specification:

1. Install the Speakeasy CLI

If you haven’t already, install the Speakeasy CLI:

# Homebrew (macOS)
brew install speakeasy-api/homebrew-tap/speakeasy

2. Generate a TypeScript SDK

If you haven’t already generated a TypeScript SDK, run:

# For first-time SDK generation
speakeasy quickstart

Follow the prompts to select TypeScript as your target language and complete the SDK configuration.

3. Enable MCP Server in Your Configuration

Open the .speakeasy/gen.yaml file in your SDK directory and add the enableMCPServer flag:

4. Regenerate Your SDK with MCP Server

Navigate to the folder that holds the TypeScript SDK and run the following command to regenerate your SDK with the MCP server:

speakeasy run

This will add a new src/mcp-server directory to your SDK containing all the MCP server code:

Your README.md will also get a new section under the “SDK Installation” section with instructions on how to install the server, and a bin section is added to package.json which points to the executable entrypoint for the server.

Using the MCP Server

Basic Setup

Here’s an example of how to launch a basic MCP server defined in a claude_desktop_config.json file:

The env property is used to make environment variables available to the server, while args after start allow you to customize specific attributes of the server.

Using Standalone Binaries

MCP server standalone binaries are automatically built and added to GitHub Releases for published SDKs:

curl -L -o mcp-server \
    https://github.com/{org}/{repo}/releases/download/{tag}/mcp-server-bun-darwin-arm64 && \
chmod +x mcp-server

If the repo is private, you must add your GitHub PAT to download a release:

curl -L -o mcp-server \
    -H "Authorization: Bearer {GITHUB_PAT}" \
    https://github.com/{org}/{repo}/releases/download/{tag}/mcp-server-bun-darwin-arm64 && \
chmod +x mcp-server

Example configuration with standalone binary:

Running MCP Locally During Development

For local development and testing, you can run the MCP server directly without publishing:

1. Make your changes to the SDK
2. Execute npm run build to rebuild the MCP server (requires Node v20+)
3. Use this configuration to run it:

Customizing MCP Tools

You can customize how your API operations are exposed as MCP tools using the x-speakeasy-mcp OpenAPI extension.

Configuration Options

The x-speakeasy-mcp extension can be used on any operation to customize the MCP tool:

disabled (optional, default: false)

If set to true, the generator will not create the MCP tool for this operation.

name (optional)

The name of the MCP tool. The default value is derived from operationId, tags, x-speakeasy-name-override, and x-speakeasy-name-group. In the example above, the default name would be products_create-product.

scopes (optional)

Scopes are a way to tag tools so that users can choose which set of tools they want to mount when the MCP server starts. For example, tagging relevant operations with a read scope allows users to start a server in read-only mode.

description (optional)

The description of the MCP tool that is passed as context to MCP clients and language models. The default value is the OpenAPI operation summary and description. It’s a good practice to review and customize these descriptions for better context.

Using Overlays

Overlays are a convenient way to add the x-speakeasy-mcp extension to existing OpenAPI documents without modifying them. To create an Overlays file, you can use the Overlay Playground .

Example of adding scopes based on HTTP methods:

Advanced Usage

Specifying Scopes at Runtime

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

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

Specifying Individual Tools

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

Next Steps

• Learn more about the Model Context Protocol 
• Explore MCP Clients  that can integrate with your server
• Read about AI Agents and how they can interact with your API