Registering Custom MCP Tools

Optionally add destructive confirmation, discovery keywords, or caller information.

Write the tool class

A tool is an @Injectable() class with the @McpTool decorator and an execute(ctx, input) method. Implement McpToolHandler from @vendure/mcp-sdk for type-safety:

To refuse a call, throw an error that extends I18nError from @vendure/core. It can be a core class such as UserInputError, or a class your plugin defines.

What the agent receives depends on how the tool ends:

Tool names share a flat namespace within each toolset, including built-in tools. Use a plugin-specific prefix such as wishlist_add_item rather than a generic name such as add_item, to avoid colliding with a future Vendure release.

Register it as a provider

Register the class as a provider in the plugin that owns it:

The MCP registry discovers every @McpTool provider across the running app at bootstrap. To confirm the tool is being served, list the tools with the MCP Inspector: see Test & debug with the MCP Inspector.

Define input and output schemas

inputSchema accepts either a plain JSON Schema object (McpJsonSchema) or a Standard Schema object (McpStandardSchema) from a library such as Zod 4, ArkType, or Valibot. Zod users need Zod 4.2 or later: Zod 3 cannot produce the JSON Schema that MCP requires.

With a Standard Schema, the schema library validates and parses the input before execute() is called. The server converts the schema to JSON Schema once at startup to advertise the tool. You define the shape once and derive the TypeScript type from it:

To avoid a schema library, use a plain JSON Schema object instead, as the first example on this page does. In either form, the server validates every call's arguments before your execute runs. There is no per-request validation to wire up. A schema that is neither form is a TypeScript error at the decorator. If a neither-form schema reaches the registry anyway, startup aborts with an error naming the offending tool.

• Omitting inputSchema means the tool accepts no arguments (the server publishes { type: 'object', properties: {}, additionalProperties: false }), not "accepts anything".
• Hand-written JSON Schemas should declare additionalProperties: false so unknown fields are rejected. Zod strips unknown keys by default. Use z.strictObject() to reject them instead.

Set permissions

permissions is a list of Permission values. Multiple permissions use OR semantics: the caller only needs one of the listed permissions.

If any administrator may call it, say so with [Permission.Authenticated]. An explicit [Permission.Public] behaves the same on the admin endpoint but reads as "anonymous allowed".

Permission.Owner is refused at startup. It is not a granted permission, so no MCP caller could ever pass it. Use [Permission.Authenticated] and check ownership inside the tool.

If your config sets an EntityAccessControlStrategy, tool calls go through it:

• canAccess() can refuse a tool that permissions allows, and tool listings leave a refused tool out. Unlike GraphQL, it cannot allow a tool that permissions refuses.
• canAccess() runs once per distinct permission list on each MCP request. Tools with the same list share the result. A throw refuses those tools and is logged.
• canAccess() receives the tool's permissions, or [Permission.Public] for a Shop tool that declares none.
• prepareAccessControl() runs on the context passed to the tool handler, so applyAccessControl() filters the queries made with that context. A tool or Core service can copy the context, for example to open its own transaction. Data your strategy stores per context object is not found on the copy, so key it on something a copy keeps, such as ctx.session.

Optional: Use the shopper's active order

Set usesActiveOrder: true on a Shop tool that uses the shopper's active Order (cart). This lets anonymous callers continue the same cart across tool calls 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.

Session creation depends on the tool's behavior:

• readonly tools only use an existing session.
• mutating and confirmed destructive tools create an anonymous session when needed.

Leave usesActiveOrder unset for tools that do not need the shopper's cart.

To add to the cart, get the cart with findOrCreateActiveOrder instead of ActiveOrderService.getActiveOrder(ctx, undefined, true). It locks the session row first, so two calls that run at the same time on one session add to one cart and do not create two. It returns the cart and a RequestContext in the cart's currency. Pass that context to the core calls that change the cart. You can call it from a service that your tool calls, with the ctx the tool received.

Optional: Require confirmation on a destructive tool

Use behavior: 'destructive' for tools that delete, cancel, refund, or otherwise make an irreversible or difficult-to-reverse change. The registry then does the confirmation handshake for you:

• It advertises an optional confirm: boolean parameter on the tool's schema.
• Without confirm: true, it returns a non-error approval request with the tool's name and description, never its arguments; your execute is not run.
• On confirm: true, it strips confirm and runs your execute.

This holds for both schema forms. For a Standard Schema tool, the registry validates your fields with your schema and handles confirm itself. Even a strict Zod schema never sees it. One constraint: a destructive tool's schema must parse to a plain object. A schema whose output is transformed to a string or an array is rejected at call time.

See How tool safety is derived for what each behavior value means.

Optional: Add discovery keywords

The optional keywords field is used only when tools are discovered through search_tools. In discovery mode the server ranks tools against a user's search_tools query. Your keywords join the tool's name, title, and description in the searchable text. Use keywords for synonyms or phrases that users might search for but that do not appear in the tool's name or description:

Keywords are never serialized into a tool listing or sent to the agent. They only tune search. They have no effect in the default direct exposure mode. See Tool exposure for how discovery works.

Metadata quick reference

The full field list, types, and defaults are on McpToolMetadata. In brief:

Optional: Read caller identity

execute(ctx, input) is enough for almost every tool. To learn who is calling, execute takes an optional third argument, McpCallerInfo, from @vendure/mcp-sdk. It carries the OAuth grant behind the call and the client IP:

caller is always passed. Its fields vary by call type:

A tool never needs to depend on @vendure/mcp-plugin. Everything a tool implements comes from @vendure/mcp-sdk.

Troubleshooting

See also

• McpToolMetadata — the full field list, types, and defaults.
• Built-in Tool Reference — the tools Vendure ships, behavior values, and exposure modes.
• Test & debug with the MCP Inspector — list and call your tool interactively.