MCP tools reference

Every tool the ShopsBuilder MCP server (https://mcp.shopsbuilder.app/mcp) offers, by class. To connect a client, see Connect an AI agent.

Classes follow the tool annotations: readOnlyHint is Read, destructiveHint is Sensitive write (as is create_store), and everything else is Write. Every tool except list_stores, create_store, select_store, current_store and report_missing_capability works on the selected store.

Read

Read only. Nothing in your store changes.

Tool	Title	Effect
`channels`	Fetch channels	Lists the store's channels.
`check_channel_readiness`	Check channel readiness	Explains why a channel's products can't be bought.
`current_domain`	Get store API URL	Shows the selected store's API URL.
`current_store`	Get selected store	Shows the selected store.
`customers`	Fetch customers	Lists customers.
`get_product_pricing`	Get product pricing	Shows a product's prices and discounts in a channel.
`get_product_variant_options`	Get product variant options	Lists a product's variant options.
`list_categories`	List categories	Lists categories.
`list_product_media`	List product media	Lists a product's images.
`list_promotions`	List promotions	Lists promotions.
`list_sales`	List sales	Lists sales.
`list_shipping_rates`	List shipping rates	Lists shipping rates and their channels.
`list_shipping_zones`	List shipping zones	Lists shipping zones.
`list_stores`	List stores	Lists your stores.
`list_warehouses`	List warehouses	Lists warehouses.
`order_count`	Fetch orders count	Counts orders.
`orders`	Fetch orders	Lists orders.
`products`	Fetch products	Lists products.
`sales_summary`	Sales summary	Summarises sales for 7 or 30 days.
`stocks`	Fetch stocks	Lists stock levels.
`warehouse_details`	Fetch warehouse details	Shows a warehouse.

Write

Creates or adds. Nothing existing is overwritten or deleted.

Tool	Title	Effect
`add_channel_to_shipping_zone`	Add channel to shipping zone	Adds a channel and countries to a shipping zone.
`add_product_image_from_url`	Add product image from URL	Adds an image to a product from a URL.
`add_product_media`	Add product media	Adds a video to a product.
`add_product_media_bulk`	Add product media in bulk	Adds several images to a product.
`add_product_media_from_upload`	Add product media from uploaded key	Adds an uploaded image to a product.
`add_product_to_featured_collection`	Add product to Featured collection	Adds a product to the Featured collection.
`add_warehouse_to_channel`	Add warehouse to channel	Connects warehouses to a channel.
`create_catalogue_promotion`	Create catalog promotion	Creates a catalog promotion.
`create_category`	Create category	Creates a category.
`create_channel`	Create channel	Creates a channel.
`create_presigned_upload_urls`	Create presigned upload URLs	Returns temporary upload URLs for images.
`create_product`	Create product	Creates a product.
`create_product_type`	Create product type	Creates a product type.
`create_product_variant`	Create product variant	Creates a product variant.
`create_sale`	Create sale	Creates a sale.
`create_shipping_rate`	Create shipping rate	Creates a shipping rate.
`create_variant_dimension`	Create variant dimension	Creates a variant option, such as size, and assigns it.
`ensure_featured_collection`	Ensure Featured collection	Creates the Featured collection if it's missing.
`report_missing_capability`	Report missing capability	Sends us a request for a missing feature.
`select_store`	Select store	Selects the store the agent works on.

Sensitive write

Overwrites or deletes existing data, or creates a store. Tools marked Yes run only after you confirm a preview.

Tool	Title	Effect	Confirmation
`add_category_image_from_upload`	Add category image from uploaded key	Replaces a category's image with an upload.	No
`add_category_image_from_url`	Add category image from URL	Replaces a category's image from a URL.	No
`create_store`	Create store	Creates a new store.	Yes
`delete_product_media`	Delete product media	Deletes product images.	Yes
`delete_promotion`	Delete promotion	Deletes a promotion.	Yes
`delete_sale`	Delete sale	Deletes a sale.	Yes
`publish_product_to_channel`	Publish product to channel	Publishes a product to a channel or changes its listing.	No
`set_collection_channels`	Set collection channels	Publishes or hides a collection in channels.	When hiding
`set_shipping_rate_price`	Set shipping rate price	Overwrites a shipping rate's price in channels.	No
`set_variant_price`	Set variant price in channel	Overwrites a variant's price in a channel.	No
`set_variant_stock`	Set variant stock	Overwrites a variant's stock in a warehouse.	No
`update_product_category`	Set product category	Replaces a product's category.	No
`update_sale_channel_listing`	Set sale discount in channel	Overwrites a sale's discount in a channel.	No
`update_shop_metadata`	Update shop profile	Overwrites the store profile: name, descriptions, images, hours and links.	No

Confirmation

create_store returns a preview when called with confirmed: false, and creates the store only when called again with confirmed: true. The delete tools, and set_collection_channels when it hides a collection, return a preview and a confirmation_token. Pass the token back only after the user confirms. The server rejects a token used for other arguments, another store or another user, as well as an expired or reused one.

Status handling

A new store takes a few minutes to provision. Until it's ready, store tools report that provisioning isn't ready. Retry the same tool shortly.

Catalog setup tools return nextStep, the next call in the flow: create_product → update_product_category → create_product_variant → publish_product_to_channel → set_variant_price → set_variant_stock.

Errors

Write tools return failures as a result, not a protocol error:

{
  "success": false,
  "error": { "code": "INVALID_INPUT", "field": "slug", "message": "…", "retryable": false },
  "errors": [{ "code": "INVALID_INPUT", "field": "slug", "message": "…", "retryable": false }]
}

retryable: true (code UPSTREAM_UNAVAILABLE) means the call can be repeated. Invalid arguments come back as an MCP tool error naming the field. An unexpected server error returns a support reference.

If no tool can do what the user asks, call report_missing_capability with a one-sentence summary and tell the user it isn't supported.

Rate limits

There is no per-tool rate limit. Access tokens are short-lived, and the client renews them through OAuth. When the store's API is overloaded, tools return retryable: true. Wait a few seconds before retrying.