Describes a single MCP tool. Attach this to a class with the McpTool decorator; the MCP server finds those classes on startup and exposes each one to agents.
stringThe name of the tool, unique within its toolset, in snake_case, e.g. search_products.
The names search_tools and execute_tool are reserved for the discovery meta-tools.
The server refuses to start if a tool takes a reserved name, or a name already used in
the same toolset.
stringA short title for people to read, passed to the client and indexed for search_tools
queries.
stringA plain description of what the tool does, written for an AI agent to read. It is sent to
the client with the tool list, and indexed for search_tools queries. For a destructive
tool it is repeated in the confirmation prompt.
string[]Extra search terms for the tool: synonyms and phrasings a user would actually say, e.g.
['money back', 'reimburse'] for a refund tool. They are indexed with the name, title and
description to match search_tools queries in discovery mode. They are never shown to the
agent or returned in a tool result.
McpToolsetA shop tool appears on the MCP shop endpoint, an admin tool on the admin endpoint.
Names only have to be unique within one toolset.
Permission[]The permissions needed to call the tool. The caller only needs one of them, the same OR
logic as the Allow decorator.
On a shop tool, omitting this or passing an empty array makes the tool public: every
caller passes the permission check, including anonymous ones.
On an admin tool it is required. The server refuses to start when it is omitted or empty.
Use [Permission.Authenticated] if any signed-in administrator may call the tool.
McpToolBehavior'mutating'How the tool behaves, which decides how it is exposed to the agent:
readonly: the tool changes nothing. Its readOnlyHint and idempotentHint
annotations are set to true.mutating: the tool writes data and runs immediately.destructive: the tool writes data and must be confirmed first. Its destructiveHint
annotation is set to true. An optional confirm field is added to the input schema the
caller sees. The registry refuses to run the tool unless the call passes confirm: true.
A destructive tool must not declare a confirm property of its own.booleanfalseSet to true for Shop tools that use the shopper's active Order. This enables anonymous
callers to continue the same cart using a sessionToken.
When the shopper already has a cart, ctx.currencyCode is the cart's currency instead of the
channel's default, so changes to the cart keep its currency and prices.
Only valid for Shop tools. The sessionToken field is managed automatically.
McpToolSchemaThe schema for the tool's arguments. Two forms are accepted: a plain JSON Schema object (McpJsonSchema), or a Standard Schema object that can emit JSON Schema (McpStandardSchema), such as a Zod v4 schema. The registry compiles the schema once at startup, and validates every call's arguments against it. A tool that omits it takes no arguments.
McpToolSchemaThe schema for the tool's return value, in the same two forms as inputSchema. The registry
validates each result against it and logs a warning on a mismatch. The call still succeeds,
and the schema is not advertised to the client.
Architecture reviews, custom plugin work, migrations, ongoing support. Get a hand from the team that builds Vendure.
Talk to the team