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.

title (optional)

A human-friendly display name for the tool. While name serves as the programmatic identifier, title provides a readable name shown in client interfaces like VS Code Copilot Chat. For example, a tool with name: "search_repositories" could have title: "Search repositories" for better user experience.

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.

readOnlyHint (optional, default: false)

Indicates whether the tool modifies its environment. Set to true for tools that only read data without making changes.

destructiveHint (optional, default: true)

Indicates whether the tool performs destructive updates to its environment. Set to false for tools that only perform additive updates. This property is meaningful only when readOnlyHint is false.

idempotentHint (optional, default: false)

Indicates whether calling the tool repeatedly with the same arguments has no additional effect on its environment. Set to true for idempotent operations. This property is meaningful only when readOnlyHint is false.

openWorldHint (optional, default: true)

Indicates whether the tool interacts with an “open world” of external entities. Set to false for tools whose domain of interaction is closed. For example, a web search tool has an open world, whereas a memory tool does not.

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: