Generate MCP servers from OpenAPI/Swagger

Experimental

The MCP server feature is currently experimental. The AI tools ecosystem is nascent and we plan to keep iterating on it. There may be breaking changes for this feature within the minor/patch version ranges of a TypeScript SDK release.

Model Context Protocol (opens in a new tab) (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 (opens in a new tab) desktop app or Cursor (opens in a new tab) code editor. The full list of clients is available here (opens in a new tab).

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

Temporary restriction

MCP server generation is only supported for TypeScript SDKs using responseFormat: flat.

<sdk-root>/.speakeasy/gen.yaml

typescript:
  responseFormat: flat
  enableMCPServer: true

What’s generated

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

bluesky-ts/src/mcp-server
├── tools
│   ├── accountDelete.ts
│   ├── accountExportData.ts
│   ├── accountsGetInviteCodes.ts
│   ├── actorGetSuggestions.ts
│   ├── ...
├── build.mts
├── mcp-server.ts
├── resources.ts
├── server.ts
├── shared.ts
└── tools.ts

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:

paths:
  /products:
    post:
      operationId: createProduct
      tags: [products]
      summary: Create product
      description: API endpoint for creating a product in the CMS
      x-speakeasy-mcp:
        disabled: false
        name: create-product
        scopes: [write, ecommerce]
        description: |
          Creates a new product using the provided form. The product name should
          not contain any special characters or harmful words.
      requestBody:
        # ...
      responses:
        # ...

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:

Create product

API endpoint for creating a product in the CMS

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 (opens in a new tab).

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

overlay: 1.0.0
info:
  title: Add MCP scopes
  version: 0.0.0
actions:
  - target: $.paths.*["get","head","query"]
    update: { "x-speakeasy-mcp": { "scopes": ["read"] } }

  - target: $.paths.*["post","put","delete","patch"]
    update: { "x-speakeasy-mcp": { "scopes": ["write"] } }

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.

{
  "mcpServers": {
    "Todos": {
      "command": "npx",
      "args": ["-y", "--", "todos", "mcp", "start"]
      "env": {
        "TODOS_API_TOKEN": "..."
      }
    }
  }
}

Specifying Scopes

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

{
  "mcpServers": {
    "Todos": {
      "command": "npx",
      "args": ["-y", "--", "todos", "mcp", "start", "--scope", "read"]
      "env": {
        "TODOS_API_TOKEN": "..."
      }
    }
  }
}

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.

{
  "mcpServers": {
    "Todos": {
      "command": "npx",
      "args": ["-y", "--", "todos", "mcp", "start", "--tool", "my_tool_1", "--tool", "my_tool_2"]
      "env": {
        "TODOS_API_TOKEN": "..."
      }
    }
  }
}