Reference

Tool reference

All 17 Shop MCP tools, what each one needs, how they're annotated, and the arguments they have in common.

Shop MCP serves 17 tools. tools/list returns each one with a description, an input schema and annotations. The guides linked below show how to use them, and the input schema is the exact reference for each argument.

Tool	What it does	Sign-in	CLI
`search_catalog`	Searches for products by text, a similar product or a photo	Optional	`shop search`
`lookup_catalog`	Finds products from IDs, GTINs or URLs you already have	Optional	`shop catalog lookup`
`get_product`	Gets one product’s details and options, and resolves a variant	Optional	`shop catalog get`
`create_cart`	Saves items in a cart at one merchant	Optional	`shop cart create`
`get_cart`	Reads a cart	Optional	`shop cart get`
`update_cart`	Replaces a cart’s contents	Optional	`shop cart update`
`create_checkout`	Starts a checkout at one merchant	Optional	`shop checkout create`
`get_checkout`	Reads a checkout	Optional	`shop checkout get`
`update_checkout`	Replaces a checkout’s details, such as items or delivery	Optional	`shop checkout update`
`complete_checkout`	Pays for a checkout and places the order	Optional	`shop checkout complete`
`search_orders`	Searches the shopper’s orders and shipments	Required	`shop order search`
`get_account`	Reads the shopper’s profile, addresses and payment options	Required	`shop account`
`create_approval`	Asks the shopper to approve a purchase outside Shopify	Required	`shop approval create`
`get_approval`	Reads an approval, and returns the card once it’s approved	Required	`shop approval get`
`update_approval`	Changes an approval’s limit, items, totals or address	Required	`shop approval update`
`cancel_approval`	Cancels an approval	Required	`shop approval cancel`
`complete_approval`	Records how the purchase went	Required	`shop approval complete`

With a token, the tools that don’t require sign-in run as the signed-in shopper. Authentication covers tokens, and these guides cover the tools:

Search the catalog: search_catalog, lookup_catalog and get_product.
Check out: the cart and checkout tools.
Track orders: search_orders.
Connect a Shop account: get_account.
Approvals: the five approval tools.

There are no tools to cancel a cart or a checkout, or to read a single order by its ID.

Annotations

Tools	`readOnlyHint`	`destructiveHint`	`idempotentHint`
`search_catalog`, `lookup_catalog`, `get_product`, `get_cart`, `get_checkout`, `search_orders`, `get_account`	`true`	`false`	`true`
Every other tool	`false`	`true`	`false`

get_approval counts as a write: reading an approved approval has Shop issue a card. Every tool has openWorldHint: true, because each call reaches the catalog, a merchant or Shop.

Arguments

Tool	Arguments	Required
`search_catalog`	`catalog`: `query`, `like`, `context`, `filters`, `pagination`, `catalog_id`, `signals`	`catalog`, with `query` or `like`
`lookup_catalog`	`catalog`: `ids`, `context`, `filters`, `signals`	`catalog.ids`, 1 to 50
`get_product`	`catalog`: `id`, `selected`, `preferences`, `context`, `filters`, `signals`	`catalog.id`
`create_cart`	`shop`, `cart`, `meta`	`shop`, `cart.line_items`
`get_cart`, `get_checkout`	`shop`, `id`	Both
`update_cart`	`shop`, `id`, `cart`, `meta`	`shop`, `id`, `cart.line_items`
`create_checkout`	`shop`, `checkout`, `meta`	`shop`, `checkout.line_items`
`update_checkout`	`shop`, `id`, `checkout`, `meta`	`shop`, `id`, `checkout.line_items`
`complete_checkout`	`shop`, `id`, `checkout`: `payment`, `signals`, and `meta`	`shop`, `id`, `checkout.payment`
`search_orders`	`query`, `activity`, `date_from`, `date_to`, `pagination`	None
`get_account`	None	None
`create_approval`	`approval`, `meta`	`approval`
`get_approval`, `cancel_approval`	`id`, and `meta` for `cancel_approval`	`id`
`update_approval`	`id`, `approval`, `meta`	`id`, `approval`
`complete_approval`	`id`, `result`	Both

`shop`

The merchant for a cart or checkout. Pass the seller.domain of the product’s offer exactly, as a hostname with no scheme or path, such as tog24.myshopify.com. Each cart or checkout belongs to one merchant, and every later call on it takes the same shop.

`id`

The ID that a create returned. Cart and checkout IDs are opaque, so pass them back exactly as you got them. Approval IDs are UUIDs.

`meta.idempotency-key`

A UUID that marks repeated sends of one write as the same operation. Reuse it when you repeat a request, and make a new one for each new operation. complete_checkout makes one from the request when you leave it out, but never send a completion twice. Retries explains when it’s safe to repeat a write.

meta takes nothing else. Shop MCP adds its own agent profile when it calls the catalog and merchants.

`signals`

The catalog, cart and checkout tools accept signals, with facts your platform observed about the shopper’s request:

Signal	Value
`dev.ucp.buyer_ip`	The shopper’s IP address
`dev.ucp.user_agent`	The user agent of the shopper’s browser or app

Shop MCP passes them on to the catalog or merchant. Send them only when your platform observed them, as a server acting for a shopper’s browser can. Without them, Shop MCP uses what it sees of the request itself: its IP address, or the leftmost X-Forwarded-For address, and its User-Agent or the MCP client name.

When you update a cart or checkout, remove the signals that came back in the copy you read before you send it.

Results

A result has the tool’s document in structuredContent, and the same document as a JSON string in content[0].text, for clients that only read text. The tools don’t publish an output schema.

Documents can carry messages, with warnings and errors to show the shopper or act on, and next, with Shop MCP’s suggestions for an agent working with the result. A failed call has isError: true, and some failures have only text. Errors and retries covers each kind.