Customize Tools

You can customize how your API operations are exposed as MCP tools using the x-speakeasy-mcp OpenAPI extension. This allows you to control tool names, descriptions, scopes, and whether specific operations should be included in your MCP server.

Set the 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)

This is 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)

You can use scopes 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)

Each MCP tool description 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.

Use overlays

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

For example, you can add scopes based on HTTP methods:

Advanced usage

Specify scopes at runtime

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

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: