Generate MCP servers from OpenAPI/Swagger

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 include a Model Context Protocol (MCP) server which allows them to be integrated with by any supported client.

Prerequisites

To turn on MCP server generation just set enableMCPServer to true in your gen.yaml file and regenerate your SDK on Github or by executing speakeasy run locally

What’s generated

The MCP server code will live in a new folder generated in the SDK under src/mcp-server:

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. This is what MCP client’s install command will use.

Configuring generated tools

The x-speakeasy-mcp OpenAPI extension can be used on any operation to customize the MCP tool that will be generated for it. The extension is used like this:

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, x-speakeasy-name-group and is usually sufficient. In the example above, the default name of the tool 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 will allow users to start a server in a read-only mode. This adds a level of safety which prevents a client from accidentally modifying or deleting data while exploring.

description (optional)

The description of the MCP tool that is passed as context to a MCP clients and language models. The default value for a tool’s description is the OpenAPI operation summary. In the example above, the description would be:

Often times, the default description may not have enough useful context so it’s a good idea to review generated descriptions and override them with this option.

Using overlays

Overlays are a convenient way to introduce the x-speakeasy-mcp extension to existing OpenAPI documents. To easily create an Overlays file, you can use our Overlay Playground .

Example of adding scopes to operations based on the HTTP method:

MCP Server Usage

Here’s an example of how to launch a basic MCP server defined in a claude_desktop_config.json file. Notice that the env property is used to make environment variables available to the server while args after start allow one to customize specific attributes of the server.

Running Standalone Binaries

MCP server standalone binaries are automatically built and added to Github Releases for published SDKs.

If the repo is a private repo you must add your Github PAT to download a release -H "Authorization: Bearer {GITHUB_PAT}".

Running MCP Locally

Releasing an npm package every time one wants to test their custom changes can be very time-consuming. Luckily, it is relatively easy to directly run MCP server changes locally.

After each change, execute npm run build to rebuild the MCP server. Ensure you have Node V20 or above installed.

Specifying Scopes

Scopes allows one to specify which set of tools they want to mount when the MCP server starts.

Specifying Tools

One can further narrow the subset of tools mounted on an MCP server. This is done by passing specific tool names in via arguments.