Storefront Catalog MCP

The Shopify AI Toolkit installs the ucp skill, which lets agents in Cursor, Claude Code, and other compatible IDEs scope catalog operations to a single merchant. Ask your assistant in natural language ("search nike.com for running shoes") and the skill picks the right UCP CLI command, or pass --business <merchant-url> on any ucp catalog command directly in a terminal.

Use --input-schema against any of these commands to fetch the merchant's live input schema before composing a payload.

Replace storedomain with the store's actual domain. The /api/ucp/mcp endpoint requires an agent profile — every request must include a meta.ucp-agent.profile URL pointing to your agent's UCP profile. The returned tools depend on the capabilities your agent advertises.

• search_catalog: Search the store's product catalog.
• lookup_catalog: Batch lookup products or variants by identifier.
• get_product: Get full product details with variant selection.
• search_locations: List or search the store's physical locations.
• lookup_locations: Batch lookup locations by identifier.

The location tools are listed only for stores with a physical retail location. Refer to Location tools for the requirements.

For Shopify-specific extension fields (additional filters and variant fields), see Storefront Catalog extension.

Searches the store's product catalog.

The response conforms to the UCP catalog search response, including a UCP metadata envelope; products with title, description, price range (minor units), media, and variants; and cursor-based pagination.

When to use:

• A customer asks "Do you have any organic coffee?"
• You need to find products matching specific criteria.
• A customer wants to browse items in a category.

Anchor to ParametersParameters

All parameters are wrapped in a catalog object. Refer to the UCP catalog search spec for the complete schema.

Free-text search query. For example, "organic coffee beans", "winter jacket".

Buyer signals for relevance and localization (address_country, language, currency, intent).

Cursor-based pagination controls. Accepts cursor (string, opaque cursor from a previous response) and limit (integer, min 1, default 10, max 250).

Retrieve products or variants by identifier.

The response conforms to the UCP catalog lookup response, including products with inputs correlation on each variant and not_found messages for unresolved identifiers.

When to use:

• You have product or variant IDs from search results or deep links.
• You need to resolve multiple identifiers in a single request.
• You're validating cart items against current catalog data.

Anchor to ParametersParameters

All parameters are wrapped in a catalog object. Refer to the UCP catalog lookup spec for the complete schema.

Array of product or variant identifiers (up to 10). For example, "gid://shopify/Product/123".

Retrieves full details for a single product with optional variant selection.

The response conforms to the UCP catalog get_product response including product.selected reflecting effective option selections, option values with available or exists signals, and variants matching the selection.

When to use:

• A customer has selected a product and needs full details.
• You need to show variant options with availability signals.
• A customer is making option selections (Color, Size, etc.).

Anchor to ParametersParameters

All parameters are wrapped in a catalog object. Refer to the UCP catalog lookup spec for the complete schema.

Product or variant identifier. For example, "gid://shopify/Product/123".

Option selections for variant narrowing. For example, [{"name": "Color", "label": "Blue"}].

Use the location tools to find a merchant's physical stores. They're served from the same endpoint as the catalog tools, so you can pass variant IDs from search_catalog to search_locations to find stores that have those products.

The location tools are listed only when both of the following are true:

• The store has at least one active location that sells in person.
• Your agent profile declares the dev.ucp.common service and the dev.ucp.common.location.search and dev.ucp.common.location.lookup capabilities. The example location profile declares only these. To use the catalog tools in the same session, declare their capabilities too.

Lists or searches the store's physical locations.

The response conforms to the UCP location search response, including a UCP metadata envelope, the matching locations, and cursor-based pagination. Each location includes an ID, name, and address, plus a phone number and coordinates when the merchant has set them. When you pass distance, locations are sorted nearest first. Otherwise, they're returned in a stable order.

When to use:

• A customer asks "Where are your stores?"
• A customer asks "Is there a store near me?" Geocode their address and pass the coordinates as distance.center.
• A customer wants to know which stores have a specific product available.

Anchor to ParametersParameters

All parameters are wrapped in a location object. An empty location object lists all of the store's locations. Refer to the UCP location search spec for the complete schema.

Free-text filter on the location's name and address. Every word must match. For example, "downtown", "Queen Street".

Radius filter. Takes a center with latitude and longitude, and a max distance in meters. Matching locations are sorted nearest to the center first. Your agent must supply the center, because it isn't inferred from context or the caller's IP address.

Product variant IDs that must all be available at a location (up to 10). For example, "gid://shopify/ProductVariant/456". Availability comes from the same store availability as the Storefront API's storeAvailability field, and doesn't guarantee stock. items is the only supported filter. Other filters keys and serves return an invalid_input error.

Buyer signals. address_country and language are used to resolve filters.items. Other fields are ignored.

Cursor-based pagination controls. Accepts cursor (string, opaque cursor from a previous response) and limit (integer, min 1, default 10, max 250).

Retrieves locations by identifier.

The response conforms to the UCP location lookup response, including an inputs array on each location that lists the request IDs that resolved to it. Unknown IDs are left out of the result. In the example, gid://shopify/Location/9999 doesn't exist, so only one location is returned.

When to use:

• You have location IDs from search results and need fresh details.
• A customer picked a store earlier in the conversation and you want to show it again.
• You want to check whether specific stores have certain items available.

Anchor to ParametersParameters

All parameters are wrapped in a location object. Refer to the UCP location lookup spec for the complete schema.

Location IDs returned by search_locations (up to 10). For example, "gid://shopify/Location/1001".

Radius filter applied to the resolved locations, with the same shape as the search_locations distance parameter. Unlike search, lookup keeps the order of ids instead of sorting by distance.

Product variant IDs that must all be available at a location. Same as the search_locations filters.items parameter.