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 restrictions

MCP server generation is only supported for TypeScript SDKs with:

• responseFormat: flat
• envVarPrefix is set to allow config options to be passed to the underlying SDK.

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

typescript:
envVarPrefix: ACME # Use a prefix that matches your project's name
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.

Customizing 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
        scope: [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.

scope (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"] } }