Skip to main content

Storefront Catalog MCP

While Global Catalog MCP provides discovery capabilities across Shopify's entire ecosystem of stores, Storefront Catalog MCP connects to an individual merchant's catalog and store policies.

Storefront Catalog MCP implements the UCP Catalog capability and its MCP binding. The names, request and response shapes of tools conform to the UCP specification.

Shopify also implements an extension to the Catalog UCP capability. Your agent may choose to advertise support for this extension, in which case Shopify-specific fields are returned in the tool responses. See the Storefront Catalog Extension documentation.

Anchor to When to use Storefront Catalog MCPWhen to use Storefront Catalog MCP

Use Storefront Catalog MCP whenever buyer intent and query are scoped to a single merchant. For example, use Storefront Catalog MCP when building a storefront AI agent. For cross-merchant product discovery, use Global Catalog MCP.

Anchor to Available toolsAvailable tools

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.

UCP catalog specification

These tools conform to the Universal Commerce Protocol catalog specification. Refer to the UCP spec for the complete request/response schema.

POST

https://{storedomain}/api/ucp/mcp

{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1,
"params": {
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://shopify.dev/ucp/agent-profiles/2026-04-08/valid-with-capabilities.json"
}
}
}
}
}

Anchor to [object Object]search_catalog

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.

catalog.query•string

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

catalog.context•object

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

POST

https://{storedomain}/api/ucp/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "search_catalog",
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://shopify.dev/ucp/agent-profiles/2026-04-08/valid-with-capabilities.json"
}
},
"catalog": {
"query": "organic coffee beans",
"context": {
"address_country": "US",
"intent": "Customer prefers fair trade products"
}
}
}
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.shopping.catalog.search": [
{"version": "2026-04-08"}
]
}
},
"products": [
{
"id": "gid://shopify/Product/1001",
"handle": "fair-trade-organic-whole-bean",
"title": "Fair Trade Organic Whole Bean Coffee",
"description": {
"html": "USDA organic whole beans; Fair Trade Certified; medium roast. Roasted in small batches."
},
"url": "https://business.example.com/products/fair-trade-organic-whole-bean",
"categories": [
{"value": "413", "taxonomy": "google_product_category"},
{"value": "fb-1-2-3", "taxonomy": "shopify"},
{"value": "Food, Beverages & Tobacco > Beverages > Coffee", "taxonomy": "merchant"}
],
"price_range": {
"min": {"amount": 1899, "currency": "USD"},
"max": {"amount": 3499, "currency": "USD"}
},
"media": [
{
"type": "image",
"url": "https://cdn.example.com/products/fair-trade-organic-whole-bean.jpg",
"alt_text": "Bag of fair trade organic whole bean coffee"
}
],
"options": [
{
"name": "Bag size",
"values": [
{"label": "12 oz"},
{"label": "2 lb"},
{"label": "5 lb"}
]
}
],
"variants": [
{
"id": "gid://shopify/ProductVariant/2001",
"sku": "FT-ORG-WB-12OZ",
"title": "12 oz",
"description": {"plain": "12 oz bag — fair trade organic whole bean"},
"price": {"amount": 1899, "currency": "USD"},
"availability": {"available": true},
"options": [{"name": "Bag size", "label": "12 oz"}],
"tags": ["organic", "fair trade", "whole bean", "coffee"]
}
],
"rating": {"value": 4.7, "scale_max": 5, "count": 312},
"metadata": {
"certifications": ["USDA Organic", "Fair Trade Certified"]
}
}
],
"pagination": {
"cursor": "eyJwYWdlIjoxfQ==",
"has_next_page": true,
"total_count": 24
}
}
}
}

Anchor to [object Object]lookup_catalog

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.

catalog.ids•arrayRequired

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

POST

https://{storedomain}/api/ucp/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "lookup_catalog",
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://shopify.dev/ucp/agent-profiles/2026-04-08/valid-with-capabilities.json"
}
},
"catalog": {
"ids": [
"gid://shopify/Product/123",
"gid://shopify/ProductVariant/456"
],
"context": {
"address_country": "US"
}
}
}
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.shopping.catalog.lookup": [
{"version": "2026-04-08"}
]
}
},
"products": [
{
"id": "gid://shopify/Product/123",
"title": "Blue Runner Pro",
"description": {
"html": "Lightweight running shoes with responsive cushioning."
},
"price_range": {
"min": {"amount": 12000, "currency": "USD"},
"max": {"amount": 12000, "currency": "USD"}
},
"variants": [
{
"id": "gid://shopify/ProductVariant/789",
"sku": "BRP-BLU-10",
"title": "Size 10",
"description": {"plain": "Size 10 variant"},
"price": {"amount": 12000, "currency": "USD"},
"availability": {"available": true},
"inputs": [
{"id": "gid://shopify/Product/123", "match": "featured"}
],
"tags": ["running", "road", "neutral"],
"seller": {
"name": "Example Store",
"links": [
{
"type": "refund_policy",
"url": "https://business.example.com/policies/refunds"
}
]
}
}
],
"metadata": {
"collection": "Winter 2026",
"technology": {
"midsole": "React foam",
"outsole": "Continental rubber"
}
}
},
{
"id": "gid://shopify/Product/880",
"title": "Trail Master X",
"description": {
"plain": "Rugged trail running shoes with aggressive tread."
},
"price_range": {
"min": {"amount": 15000, "currency": "USD"},
"max": {"amount": 15000, "currency": "USD"}
},
"variants": [
{
"id": "gid://shopify/ProductVariant/456",
"sku": "TMX-GRN-11",
"title": "Size 11 - Green",
"description": {"plain": "Size 11 Green variant"},
"price": {"amount": 15000, "currency": "USD"},
"availability": {"available": true},
"inputs": [
{"id": "gid://shopify/ProductVariant/456", "match": "exact"}
],
"tags": ["trail", "waterproof"],
"seller": {
"name": "Example Store"
}
}
]
}
]
}
}
}

Anchor to [object Object]get_product

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.

catalog.id•stringRequired

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

catalog.selected•array

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

POST

https://{storedomain}/api/ucp/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "get_product",
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://shopify.dev/ucp/agent-profiles/2026-04-08/valid-with-capabilities.json"
}
},
"catalog": {
"id": "gid://shopify/Product/123",
"selected": [
{"name": "Color", "label": "Blue"}
],
"context": {
"address_country": "US"
}
}
}
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.shopping.catalog.lookup": [
{"version": "2026-04-08"}
]
}
},
"product": {
"id": "gid://shopify/Product/123",
"handle": "runner-pro",
"title": "Runner Pro",
"description": {
"html": "Lightweight running shoes with responsive cushioning."
},
"url": "https://business.example.com/products/runner-pro",
"price_range": {
"min": {"amount": 12000, "currency": "USD"},
"max": {"amount": 15000, "currency": "USD"}
},
"media": [
{
"type": "image",
"url": "https://cdn.example.com/products/runner-pro-blue.jpg",
"alt_text": "Runner Pro in Blue"
}
],
"options": [
{
"name": "Color",
"values": [
{"label": "Blue", "available": true, "exists": true},
{"label": "Red", "available": true, "exists": true},
{"label": "Green", "available": false, "exists": true}
]
},
{
"name": "Size",
"values": [
{"label": "8", "available": true, "exists": true},
{"label": "9", "available": true, "exists": true},
{"label": "10", "available": true, "exists": true},
{"label": "11", "available": false, "exists": false},
{"label": "12", "available": true, "exists": true}
]
}
],
"selected": [
{"name": "Color", "label": "Blue"}
],
"variants": [
{
"id": "gid://shopify/ProductVariant/1001",
"sku": "BRP-BLU-10",
"title": "Blue, Size 10",
"description": {"plain": "Blue, Size 10"},
"price": {"amount": 12000, "currency": "USD"},
"availability": {"available": true},
"options": [
{"name": "Color", "label": "Blue"},
{"name": "Size", "label": "10"}
]
},
{
"id": "gid://shopify/ProductVariant/1002",
"sku": "BRP-BLU-12",
"title": "Blue, Size 12",
"description": {"plain": "Blue, Size 12"},
"price": {"amount": 15000, "currency": "USD"},
"availability": {"available": true},
"options": [
{"name": "Color", "label": "Blue"},
{"name": "Size", "label": "12"}
]
}
],
"rating": {
"value": 4.5,
"scale_max": 5,
"count": 128
}
}
}
}
}