--- title: Global Catalog MCP description: >- Use Shopify's UCP catalog tools to search, look up, and get product details from across all Shopify merchants. source_url: html: 'https://shopify.dev/docs/agents/catalog/global-catalog' md: 'https://shopify.dev/docs/agents/catalog/global-catalog.md' --- # Global Catalog MCP The Global Catalog MCP server enables AI agents to search and discover products across the entire Shopify ecosystem, helping buyers find products from multiple merchants. Global Catalog MCP implements the [UCP Catalog capability](https://ucp.dev/2026-04-08/specification/catalog/) and its [MCP binding](https://ucp.dev/2026-04-08/specification/catalog/mcp/). The names, request and response shapes of tools conform to the [UCP specification](https://ucp.dev/2026-04-08/specification/catalog/). ## When to use Global Catalog MCP Use Global Catalog MCP when your agent needs to discover products across multiple Shopify merchants — for example, comparison shopping, cross-merchant discovery, or recommendations not tied to a specific store. For single-store agents, use [Storefront Catalog MCP](https://shopify.dev/docs/agents/catalog/storefront-catalog). ## How it works Product discovery follows a two-step flow: 1. **Discover**: Your agent finds matching products using `search_catalog` or `lookup_catalog`. `search_catalog` supports a text query, an image, or a set of product IDs to find similar items. `lookup_catalog` resolves known identifiers to their current catalog data. Results are clustered by Universal Product ID (UPID) and include offers from multiple merchants. 2. **Evaluate**: Your agent calls `get_product` with a product or variant ID to explore available options and refine selection — for example, which colors are available in size medium — then retrieve pricing and seller checkout links for the buyer's chosen variant. ## Use with the AI Toolkit The [Shopify AI Toolkit](https://shopify.dev/docs/apps/build/ai-toolkit) [installs](https://shopify.dev/docs/agents#get-started) the `ucp` skill, which lets agents in Cursor, Claude Code, and other compatible IDEs reach the Global Catalog by name. Ask your assistant in natural language (`"find me crewneck sweaters under $50"`) and the skill picks the right [UCP CLI](https://github.com/Shopify/ucp-cli) command, or run `ucp catalog` directly in a terminal. The skill also knows when to search the global catalog and when to scope to a single merchant. Omit `--business` to query the global catalog; pass `--business ` to scope a search to a single merchant's storefront. ##### Search ```bash ucp catalog search \ --set /query='wireless headphones under $100' \ --set /context/address_country=US \ --view :compact \ --format md ``` ##### Lookup ```bash ucp catalog lookup \ --set '/ids/0=gid://shopify/ProductVariant/12345' ``` ##### Get product ```bash ucp catalog get_product gid://shopify/Product/67890 \ --set '/selected/0={"name":"Color","label":"Black"}' ``` ## Available tools The `/api/ucp/mcp` endpoint requires an [agent profile](https://shopify.dev/docs/agents/get-started/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_catalog): Search for products across all Shopify merchants. * [`lookup_catalog`](#lookup_catalog): Look up products or variants by identifier. * [`get_product`](#get_product): Get full product details with variant selection. **UCP catalog specification:** These tools conform to the [Universal Commerce Protocol catalog specification](https://ucp.dev/specification/catalog/). Refer to the UCP spec for the complete request/response schema. For Shopify-specific extension fields (additional filters, variant fields, and ML-inferred metadata), see [Global Catalog extension](https://shopify.dev/docs/agents/catalog/global-catalog-extension). POST ## https://catalog.shopify.com/api/ucp/mcp ```json { "jsonrpc": "2.0", "method": "tools/list", "id": 1 } ``` ### `search_catalog` Searches for products across all Shopify merchants. The response conforms to the [UCP catalog search response](https://ucp.dev/specification/catalog/search/), including a UCP metadata envelope; products with title, description, price range (minor units), media, and variants. When to use: * A customer asks "I'm looking for trail running shoes under $150." * You need to find products matching criteria from any merchant. * A customer wants to compare products across multiple stores. #### Parameters All parameters are wrapped in a `catalog` object. Refer to the [UCP catalog search spec](https://ucp.dev/specification/catalog/search/) for the complete schema. catalog.query•string Free-text search query. For example, "trail running shoes", "organic coffee beans". catalog.like•array Similar items to search by — results should resemble these inputs. Each item is one of: * Item Reference: `{"id": "gid://shopify/p/..."}` — a product or variant ID. * Image Content: `{"image": {"content_type": "image/jpeg", "data": ""}}` — a base64-encoded image with its MIME type. catalog.context•object Buyer signals for relevance and localization (`address_country`, `address_region`, `postal_code`, `language`, `currency`, and `intent`). catalog.filters.available•boolean Filter by availability. Defaults to `true` (only sale-ready items). Set to `false` to include unavailable items. catalog.filters.ships\_to•object Filter to products that ship to a given location. Accepts `country` (ISO 3166-1 alpha-2), `region`, and `postal_code`. catalog.filters.ships\_from•object Filter by merchant origin country (`country`, ISO 3166-1 alpha-2). catalog.filters.price•object Price range in minor currency units. Accepts `min` and `max` integers. For example, `{"min": 5000, "max": 20000}` = $50.00–$200.00 USD. catalog.filters.condition•array Product condition filter. Known values: `"new"`, `"secondhand"`. Multiple values use OR logic. catalog.filters.shop\_ids•array Filter to specific shop IDs. Accepts an array of shop ID strings. catalog.filters.categories•array Filter by product category using taxonomy IDs. Each item accepts `id` (required) and `taxonomy` (optional, defaults to Shopify's standard taxonomy). Multiple values use OR logic. catalog.view•string Predefined output shape for the response. Use `"offer"` for comparison shopping. When absent, the server returns its default shape. catalog.pagination•object Page size control. Accepts `limit` (integer, min `1`, default `10`, max `50`). Cursor-based pagination is not yet supported on the global catalog. #### Call from the Shopify AI Toolkit and UCP CLI With the [Shopify AI Toolkit](https://shopify.dev/docs/apps/build/ai-toolkit) [installed](https://shopify.dev/docs/agents#get-started), ask your assistant in natural language (`"find wireless headphones under $100"`) and the `ucp` skill picks the right [UCP CLI](https://github.com/Shopify/ucp-cli) command. You can also run the command directly in a terminal: ## Search ```bash ucp catalog search \ --set /query='wireless headphones under $100' \ --set /context/address_country=US \ --view :compact \ --format md ``` #### Call the tool directly POST ## https://catalog.shopify.com/api/ucp/mcp ##### cURL ```json { "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": "trail running shoes", "filters": { "ships_to": {"country": "US"}, "price": {"max": 15000}, "available": true }, "context": { "address_country": "US", "intent": "Customer runs marathons and needs road shoes" } } } } } ``` ##### {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-04-08", "capabilities": { "dev.ucp.shopping.catalog.search": [{"version": "2026-04-08"}], "dev.shopify.catalog.global": [{"version": "2026-04-08"}] } }, "products": [ { "id": "gid://shopify/p/7f3a2b8c1d9e", "title": "Trail Runner Pro", "description": { "html": "Lightweight trail running shoe designed for road and light trail." }, "url": "https://example-running.myshopify.com/products/trail-runner-pro", "categories": [ {"value": "5133", "taxonomy": "google_product_category"}, {"value": "Sporting Goods > Athletics > Running > Shoes", "taxonomy": "merchant"} ], "price_range": { "min": {"amount": 8999, "currency": "USD"}, "max": {"amount": 12999, "currency": "USD"} }, "media": [ { "type": "image", "url": "https://cdn.shopify.com/products/trail-runner-pro.jpg", "alt_text": "Trail Runner Pro running shoes" } ], "options": [ { "name": "Size", "values": [ {"label": "8"}, {"label": "9"}, {"label": "10"}, {"label": "11"} ] }, { "name": "Color", "values": [ {"label": "Black"}, {"label": "Blue"} ] } ], "variants": [ { "id": "gid://shopify/ProductVariant/12345678", "sku": "TRP-BLK-10", "title": "Black / Size 10", "description": {"plain": "Trail Runner Pro, Black, Size 10"}, "price": {"amount": 8999, "currency": "USD"}, "checkout_url": "https://example-running.myshopify.com/cart/12345678:1", "condition": ["new"], "eligible": {"native_checkout": true}, "availability": {"available": true, "status": "in_stock", "running_low": false}, "requires": {"shipping": true, "selling_plan": false, "components": false}, "options": [ {"name": "Size", "label": "10"}, {"name": "Color", "label": "Black"} ], "tags": ["road", "neutral", "lightweight"], "seller": { "name": "Example Running", "id": "gid://shopify/Shop/987654321", "domain": "example-running.myshopify.com", "url": "https://example-running.myshopify.com", "links": [ { "type": "refund_policy", "url": "https://example-running.myshopify.com/policies/refunds" } ] } } ], "rating": {"value": 4.5, "scale_max": 5, "count": 120} } ] } } } ``` ### `lookup_catalog` Retrieves products or variants by identifier from across all Shopify merchants. The response conforms to the [UCP catalog lookup response](https://ucp.dev/specification/catalog/lookup/), 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. #### Parameters All parameters are wrapped in a `catalog` object. Refer to the [UCP catalog lookup spec](https://ucp.dev/specification/catalog/lookup/) for the complete schema. catalog.ids•arrayRequired (critical) Array of product or variant identifiers (1 to 50). Accepts `gid://shopify/p/{upid}` and `gid://shopify/ProductVariant/{id}` formats. Multiple IDs that resolve to the same product are grouped into a single product in the response. catalog.filters.ships\_to•object Filter to products that ship to a given location. Accepts `country`, `region`, and `postal_code`. catalog.filters.ships\_from•object Filter by merchant origin country (`country`, ISO 3166-1 alpha-2). catalog.filters.available•boolean Filter by availability. Defaults to `true` (only sale-ready items). Set to `false` to include unavailable items. catalog.filters.condition•array Product condition filter. Known values: `"new"`, `"secondhand"`. Multiple values use OR logic. catalog.context•object Buyer context for localization (`address_country`, `address_region`, `postal_code`, `language`, `currency`, and `intent`). catalog.view•string Predefined output shape for the response. Use `"offer"` for comparison shopping. When absent, the server returns its default shape. #### Call from the Shopify AI Toolkit and UCP CLI With the [Shopify AI Toolkit](https://shopify.dev/docs/apps/build/ai-toolkit) [installed](https://shopify.dev/docs/agents#get-started), ask your assistant in natural language (`"look up this variant"`) and the `ucp` skill picks the right [UCP CLI](https://github.com/Shopify/ucp-cli) command. You can also run the command directly in a terminal: ## Lookup ```bash ucp catalog lookup \ --set '/ids/0=gid://shopify/ProductVariant/12345' ``` #### Call the tool directly POST ## https://catalog.shopify.com/api/ucp/mcp ##### cURL ```json { "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/p/7f3a2b8c1d9e", "gid://shopify/ProductVariant/87654321" ], "context": { "address_country": "US" } } } } } ``` ##### {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-04-08", "capabilities": { "dev.ucp.shopping.catalog.lookup": [{"version": "2026-04-08"}], "dev.shopify.catalog.global": [{"version": "2026-04-08"}] } }, "products": [ { "id": "gid://shopify/p/7f3a2b8c1d9e", "title": "Trail Runner Pro", "description": { "html": "Lightweight trail running shoe designed for road and light trail." }, "price_range": { "min": {"amount": 8999, "currency": "USD"}, "max": {"amount": 12999, "currency": "USD"} }, "variants": [ { "id": "gid://shopify/ProductVariant/12345678", "sku": "TRP-BLK-10", "title": "Black / Size 10", "price": {"amount": 8999, "currency": "USD"}, "checkout_url": "https://example-running.myshopify.com/cart/12345678:1", "condition": ["new"], "eligible": {"native_checkout": true}, "availability": {"available": true, "status": "in_stock", "running_low": false}, "requires": {"shipping": true, "selling_plan": false, "components": false}, "inputs": [ {"id": "gid://shopify/p/7f3a2b8c1d9e", "match": "featured"} ], "seller": { "name": "Example Running", "id": "gid://shopify/Shop/987654321", "domain": "example-running.myshopify.com", "url": "https://example-running.myshopify.com", "links": [ { "type": "refund_policy", "url": "https://example-running.myshopify.com/policies/refunds" } ] } } ] } ], "messages": [ { "type": "info", "code": "not_found", "content": "gid://shopify/ProductVariant/87654321" } ] } } } ``` ### `get_product` Retrieves full details for a single product with optional variant selection. The response conforms to the [UCP catalog `get_product` response](https://ucp.dev/specification/catalog/lookup/#response_1), including `product.selected` reflecting effective option selections, option values with `available` and `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, and so on). #### Parameters All parameters are wrapped in a `catalog` object. Refer to the [UCP catalog lookup spec](https://ucp.dev/specification/catalog/lookup/) for the complete schema. catalog.id•stringRequired (critical) Product or variant identifier. Accepts `gid://shopify/p/{upid}` or `gid://shopify/ProductVariant/{id}`. catalog.selected•array Option selections for variant narrowing. For example, `[{"name": "Color", "label": "Blue"}, {"name": "Size", "label": "10"}]`. The response reflects these selections in `product.selected` and filters the returned variants accordingly. catalog.preferences•array Option names in relaxation priority order. When an exact match isn't available, options are dropped from the end of this list first. For example, `["Color", "Size"]` drops Size before Color. catalog.filters.ships\_to•object Filter to products that ship to a given location. Accepts `country`, `region`, and `postal_code`. catalog.filters.ships\_from•object Filter by merchant origin country (`country`, ISO 3166-1 alpha-2). catalog.filters.available•boolean Filter by availability. Defaults to `true` (only sale-ready items). Set to `false` to include unavailable items. catalog.filters.condition•array Product condition filter. Known values: `"new"`, `"secondhand"`. Multiple values use OR logic. catalog.context•object Buyer context for localization (`address_country`, `address_region`, `postal_code`, `language`, `currency`, and `intent`). catalog.view•string Predefined output shape for the response. Use `"summary"` for a condensed product detail view. When absent, the server returns its default shape. #### Call from the Shopify AI Toolkit and UCP CLI With the [Shopify AI Toolkit](https://shopify.dev/docs/apps/build/ai-toolkit) [installed](https://shopify.dev/docs/agents#get-started), ask your assistant in natural language (`"show me this product in black"`) and the `ucp` skill picks the right [UCP CLI](https://github.com/Shopify/ucp-cli) command. You can also run the command directly in a terminal: ## Get product ```bash ucp catalog get_product gid://shopify/p/7f3a2b8c1d9e \ --set '/selected/0={"name":"Color","label":"Black"}' ``` #### Call the tool directly POST ## https://catalog.shopify.com/api/ucp/mcp ##### cURL ```json { "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/p/7f3a2b8c1d9e", "selected": [ {"name": "Color", "label": "Black"} ], "context": { "address_country": "US" } } } } } ``` ##### {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-04-08", "capabilities": { "dev.ucp.shopping.catalog.lookup": [{"version": "2026-04-08"}], "dev.shopify.catalog.global": [{"version": "2026-04-08"}] } }, "product": { "id": "gid://shopify/p/7f3a2b8c1d9e", "title": "Trail Runner Pro", "description": { "html": "Lightweight trail running shoe designed for road and light trail." }, "url": "https://example-running.myshopify.com/products/trail-runner-pro", "price_range": { "min": {"amount": 8999, "currency": "USD"}, "max": {"amount": 12999, "currency": "USD"} }, "media": [ { "type": "image", "url": "https://cdn.shopify.com/products/trail-runner-pro-black.jpg", "alt_text": "Trail Runner Pro in Black" } ], "options": [ { "name": "Color", "values": [ {"label": "Black", "available": true, "exists": true}, {"label": "Blue", "available": true, "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": true}, {"label": "12", "available": true, "exists": true} ] } ], "selected": [ {"name": "Color", "label": "Black"} ], "variants": [ { "id": "gid://shopify/ProductVariant/12345678", "sku": "TRP-BLK-10", "title": "Black / Size 10", "description": {"plain": "Black, Size 10"}, "price": {"amount": 8999, "currency": "USD"}, "checkout_url": "https://example-running.myshopify.com/cart/12345678:1", "condition": ["new"], "eligible": {"native_checkout": true}, "availability": {"available": true, "status": "in_stock", "running_low": false}, "requires": {"shipping": true, "selling_plan": false, "components": false}, "options": [ {"name": "Color", "label": "Black"}, {"name": "Size", "label": "10"} ], "seller": { "name": "Example Running", "id": "gid://shopify/Shop/987654321", "domain": "example-running.myshopify.com", "url": "https://example-running.myshopify.com", "links": [ { "type": "refund_policy", "url": "https://example-running.myshopify.com/policies/refunds" } ] } } ], "rating": { "value": 4.5, "scale_max": 5, "count": 120 } } } } } ```