Skip to main content

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 and its MCP binding. The names, request and response shapes of tools conform to the UCP specification.

Anchor to When to use Global Catalog MCPWhen 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.

Anchor to How it worksHow 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.

Anchor to Use with the AI ToolkitUse with the AI Toolkit

The Shopify AI Toolkit installs 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 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 <url> to scope a search to a single merchant's storefront.

ucp catalog search \
--set /query='wireless headphones under $100' \
--set /context/address_country=US \
--view :compact \
--format md
ucp catalog lookup \
--set '/ids/0=gid://shopify/ProductVariant/12345'
ucp catalog get_product gid://shopify/Product/67890 \
--set '/selected/0={"name":"Color","label":"Black"}'

Anchor to Available toolsAvailable tools

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.

For Shopify-specific extension fields (additional filters, variant fields, and ML-inferred metadata), see Global Catalog extension.

POST

https://catalog.shopify.com/api/ucp/mcp

{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}

Anchor to [object Object]search_catalog

Searches for products across all Shopify merchants.

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.

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.

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, "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": "<base64>"}} — 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.

Anchor to Call from the Shopify AI Toolkit and UCP CLICall from the Shopify AI Toolkit and UCP CLI

With the Shopify AI Toolkit installed, ask your assistant in natural language ("find wireless headphones under $100") and the ucp skill picks the right UCP CLI command. You can also run the command directly in a terminal:

Search

ucp catalog search \
--set /query='wireless headphones under $100' \
--set /context/address_country=US \
--view :compact \
--format md

Anchor to Call the tool directlyCall the tool directly

POST

https://catalog.shopify.com/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": "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"
}
}
}
}
}
{
"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}
}
]
}
}
}

Anchor to [object Object]lookup_catalog

Retrieves products or variants by identifier from across all Shopify merchants.

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 (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.

Anchor to Call from the Shopify AI Toolkit and UCP CLICall from the Shopify AI Toolkit and UCP CLI

With the Shopify AI Toolkit installed, ask your assistant in natural language ("look up this variant") and the ucp skill picks the right UCP CLI command. You can also run the command directly in a terminal:

Lookup

ucp catalog lookup \
--set '/ids/0=gid://shopify/ProductVariant/12345'

Anchor to Call the tool directlyCall the tool directly

POST

https://catalog.shopify.com/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/p/7f3a2b8c1d9e",
"gid://shopify/ProductVariant/87654321"
],
"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"}],
"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"
}
]
}
}
}

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 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).

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. 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.

Anchor to Call from the Shopify AI Toolkit and UCP CLICall from the Shopify AI Toolkit and UCP CLI

With the Shopify AI Toolkit installed, ask your assistant in natural language ("show me this product in black") and the ucp skill picks the right UCP CLI command. You can also run the command directly in a terminal:

Get product

ucp catalog get_product gid://shopify/p/7f3a2b8c1d9e \
--set '/selected/0={"name":"Color","label":"Black"}'

Anchor to Call the tool directlyCall the tool directly

POST

https://catalog.shopify.com/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/p/7f3a2b8c1d9e",
"selected": [
{"name": "Color", "label": "Black"}
],
"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"}],
"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
}
}
}
}
}