Skip to main content

Catalog MCP

The Catalog MCP server enables AI agents to search and discover products across the global Shopify ecosystem, helping buyers find products from multiple merchants and retrieve detailed product information.

Anchor to How it worksHow it works

The Catalog MCP server lets your AI agent help buyers discover products:

  • Search globally for products across all Shopify merchants based on buyer preferences and criteria.
  • Get detailed information about specific products including variants, pricing, and availability.
  • Filter results by price, location, product options, and other buyer preferences.

For usage guidelines, see About Catalog. For the UCP protocol overview, see Core concepts.

Anchor to AuthenticateAuthenticate

Obtain your client credentials (client ID and secret) from the Catalog section of Dev Dashboard.

Then use those credentials to retrieve a token for subsequent requests. All requests require the Authorization: Bearer {token} header.

POST

https://api.shopify.com/auth/access_token

curl --request POST \
--url https://api.shopify.com/auth/access_token \
--header 'Content-Type: application/json' \
--data '{
"client_id": "{your_client_id}",
"client_secret": "{your_client_secret}",
"grant_type": "client_credentials"
}'

The response contains:

  • access_token: A JWT access token that can be used to interact with the MCP server.
  • scope: The list of access scopes that were granted to your API key.
  • expires_in: The number of seconds until the access token expires.

JWT tokens created from Dev Dashboard credentials have a 60-minute TTL. You can use a JWT decoder tool like jwt.io to investigate more details related to how Shopify issues this token.

{} Response

{
"access_token": "f8563253df0bf277ec9ac6f649fc3f17",
"scope": "read_global_api_catalog_search",
"expires_in": 86399
}

All requests follow the JSON-RPC 2.0 protocol. Send

POST
requests to:

https://discover.shopifyapps.com/global/mcp

Learn more about building agentic commerce experiences.

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "tool_name",
"arguments": {
// tool-specific arguments
}
}
}

Anchor to Available toolsAvailable tools

Catalog MCP provides core tools for product discovery across all of Shopify:

  • search_global_products: Search for products across all Shopify merchants based on buyer queries and preferences.
  • get_global_product_details: Retrieve detailed information about a specific product using its Universal Product ID (UPID) or a variant ID.

Anchor to [object Object]search_global_products

Search for products across the global Shopify catalog based on buyer queries and preferences.

Use this tool when buyers are searching for products without specifying a particular shop. The tool searches across all Shopify merchants and returns relevant products based on the query, price range, shipping preferences, and other criteria.

When to use:

  • "I'm looking for a pair of shoes"
  • "Could you find me some blue jeans?"
  • "I need a new dress, I'm a size 10 and I like the color blue"
Catalog API

The search_global_products tool wraps the Search endpoint of Catalog API, which can also be used depending on your use case.

Anchor to ParametersParameters

context•stringRequired

Additional information about the request such as user demographics, mood, location, or other relevant details that could help tailor the response.

query•stringRequired

The search query to find related products. For example, "shoes", "blue jeans".

available_for_sale•boolean

When true, include only products available for sale.

When false, include unavailable items if they are a good match for the query.

include_secondhand•boolean

When true, include secondhand products in the results.

limit•integerDefault: 10

Maximum number of products to return (1-300).

max_price•number

Maximum price the buyer is willing to pay (without currency unit).

min_price•number

Minimum price the buyer is willing to pay (without currency unit).

products_limit•integerDefault: 10

The maximum number of products to return per universal product (1-10).

requires_selling_plan•boolean

When true, include only subscription products. When false, include only non-subscription products.

saved_catalog•string

The slug of a catalog saved through Dev Dashboard. While parameters set upon calling the search_global_products tool are applied, filters in the saved catalog always take precedence when a slug is provided.

ships_from•string

Filter by shipping origin (ISO country code).

ships_to•string

Filter by shipping destination (ISO country code).

shop_ids•array

Array of shop IDs to filter by specific shops.

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "search_global_products",
"arguments": {
query: 'I need a crewneck sweater',
context: 'buyer looking for sustainable fashion',
limit: 3
}
}
}

{} Response

{
"offers": [
{
"id": "gid://shopify/p/abc123def456",
"title": "Organic Cotton Crewneck Sweater",
"description": "A sustainably made crewneck sweater crafted from 100% organic cotton with a relaxed fit.",
"images": [
{
"url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck.jpg",
"altText": "Organic Cotton Crewneck Sweater - EcoWear",
"product": {
"id": "gid://shopify/Product/1234567890",
"title": "Organic Cotton Crewneck Sweater",
"onlineStoreUrl": "https://ecowear-example.myshopify.com/products/organic-cotton-crewneck?variant=11111111111&_gsid=example123",
"shop": {
"name": "EcoWear",
"onlineStoreUrl": "https://ecowear-example.myshopify.com"
}
}
}
],
"options": [
{
"name": "Size",
"values": [
{ "value": "S", "availableForSale": true, "exists": true },
{ "value": "M", "availableForSale": true, "exists": true },
{ "value": "L", "availableForSale": true, "exists": true }
]
},
{
"name": "Color",
"values": [
{ "value": "Oatmeal", "availableForSale": true, "exists": true },
{ "value": "Forest Green", "availableForSale": true, "exists": true }
]
}
],
"priceRange": {
"min": { "amount": "89.00", "currencyCode": "USD" },
"max": { "amount": "89.00", "currencyCode": "USD" }
},
"products": [
{
"id": "gid://shopify/Product/1234567890",
"title": "Organic Cotton Crewneck Sweater",
"checkoutUrl": "https://ecowear-example.myshopify.com/cart/11111111111:1?_gsid=example123&payment=shop_pay",
"description": "A sustainably made crewneck sweater crafted from 100% organic cotton. Features a relaxed fit and ribbed cuffs.",
"featuredImage": {
"url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck.jpg",
"altText": "Organic Cotton Crewneck Sweater - EcoWear"
},
"onlineStoreUrl": "https://ecowear-example.myshopify.com/products/organic-cotton-crewneck?variant=11111111111&_gsid=example123",
"price": { "amount": "89.00", "currencyCode": "USD" },
"rating": { "value": 4.8, "count": 124 },
"availableForSale": true,
"shop": {
"name": "EcoWear",
"paymentSettings": {
"supportedDigitalWallets": ["SHOPIFY_PAY"],
"acceptedCardBrands": ["visa", "master", "american_express"]
},
"onlineStoreUrl": "https://ecowear-example.myshopify.com",
"privacyPolicy": { "url": "https://ecowear-example.myshopify.com/policies/privacy" },
"refundPolicy": { "url": "https://ecowear-example.myshopify.com/policies/refund" },
"termsOfService": { "url": "https://ecowear-example.myshopify.com/policies/terms" },
"shippingPolicy": { "url": "https://ecowear-example.myshopify.com/policies/shipping" },
"id": "gid://shopify/Shop/1111111111"
},
"selectedProductVariant": {
"id": "gid://shopify/ProductVariant/11111111111?shop=1111111111",
"availableForSale": true,
"options": [
{ "name": "Size", "value": "M" },
{ "name": "Color", "value": "Oatmeal" }
],
"price": { "amount": "89.00", "currencyCode": "USD" },
"image": {
"url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck.jpg",
"altText": "Organic Cotton Crewneck Sweater - EcoWear"
}
},
"secondhand": false,
"requiresSellingPlan": false
}
],
"availableForSale": true,
"rating": { "value": 4.8, "count": 124 },
"uniqueSellingPoint": "Made from 100% GOTS-certified organic cotton with carbon-neutral shipping.",
"topFeatures": [
"100% organic cotton for breathable comfort",
"Relaxed fit with ribbed cuffs and hem",
"GOTS certified sustainable production",
"Pre-washed for softness",
"Classic crewneck design"
],
"techSpecs": [
"Material: 100% Organic Cotton",
"Fit: Relaxed",
"Neckline: Crew",
"Care: Machine wash cold"
],
"sharedAttributes": [
{ "name": "Fabric", "values": ["Cotton", "Organic"] },
{ "name": "Neckline", "values": ["Crew"] },
{ "name": "Target gender", "values": ["Unisex"] },
{ "name": "Pattern", "values": ["Solid"] }
],
"url": "https://discover.shopifyapps.com/global/v1/p/abc123def456?_gsid=example123"
}
],
"instructions": "Use markdown to render product titles as links to their respective product pages using the URL property."
}

Anchor to ExamplesExamples

Anchor to Use price and shipping filtersUse price and shipping filters

Narrow results by combining price range and shipping destination filters. This example searches for wireless headphones within a $50–$200 budget, only returning in-stock products that ship to the US.

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "search_global_products",
"arguments": {
"query": "wireless headphones",
"context": "buyer prefers noise-cancelling features, budget-conscious",
"min_price": 50,
"max_price": 200,
"ships_to": "US",
"available_for_sale": true,
"limit": 15
}
}
}
Anchor to Subscription productsSubscription products

Filter for products that require a selling plan to surface subscription-only offerings. This example finds coffee beans available as recurring subscriptions that ship to Canada.

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "search_global_products",
"arguments": {
"query": "coffee beans",
"context": "buyer interested in monthly coffee subscription",
"requires_selling_plan": true,
"ships_to": "CA",
"limit": 5
}
}
}
Anchor to Secondhand productsSecondhand products

Include pre-owned and vintage items by enabling the secondhand filter. This example searches for leather jackets under $150, expanding results to include sustainable, secondhand options.

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "search_global_products",
"arguments": {
"query": "vintage leather jacket",
"context": "buyer looking for sustainable fashion options",
"include_secondhand": true,
"max_price": 150,
"limit": 20
}
}
}

Anchor to [object Object]get_global_product_details

Retrieve detailed information about a specific product using its Universal Product ID (UPID) or a variant ID.

Identifier requirement

You must provide exactly one of upid or variant_id. Providing both returns an error.

Use this tool when a buyer is asking about a specific product and you have either the product ID or a variant ID. This tool returns comprehensive product information including all variants, detailed pricing, availability, and shop details.

When to use:

  • A buyer asks "Tell me more about this product" with a product link or ID.
  • You need to look up detailed information for a specific product.
  • You need to show variant options, pricing, and availability for a specific product.
  • You have a variant ID and need to find the Universal Product it belongs to.
Catalog API

The get_global_product_details tool wraps the Lookup and Lookup by variant endpoints of Catalog API, which can also be used depending on your use case.

Anchor to ParametersParameters

upid•stringRequired*

The Universal Product ID (in Base62 encoded format). Required if variant_id isn't provided.

variant_id•integerRequired*

A Shopify variant ID. Required if upid isn't provided. Returns the Universal Product that the variant belongs to, with that variant ranked first in results.

_gsid•string

Reference to the Global Search that generated the URL.

available_for_sale•boolean

When true, include only products available for sale.

When false, include unavailable items if they're a good match for the query.

context•string

Additional information about the request.

include_secondhand•boolean

When true, include secondhand products in the result. This doesn't mean that only secondhand products will appear in the results.

limit•integerDefault: 10

Maximum number of offers to return for the product (1-100).

option_preferences•string

Comma-separated list of option names ranked by importance (for example, "Color,Size,Material"). Filters are relaxed starting with the least important option.

product_id•integer

Pins this product to the first position in results, regardless of relevance ranking.

product_options•array

Filter by product options such as color or size. Each item has key (option name) and values (array of option values).

query•string

Additional keyword search within the product.

ships_from•string

Filter by shipping origin (ISO country code).

ships_to•string

Filter by shipping destination (ISO country code).

shop_id•string

Filter by specific shop (numeric ID or Shop GID).

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "get_global_product_details",
"arguments": {
"upid": "AbC123XyZ"
}
}
}

{} Response

{
"product": {
"id": "gid://shopify/p/xyz789abc123",
"title": "Organic Cotton Crewneck Sweater",
"description": "A soft crewneck sweater crafted from 100% organic cotton with a relaxed fit for everyday comfort.",
"images": [
{
"url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck-front.jpg",
"altText": "Organic Cotton Crewneck Sweater - Front"
},
{
"url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck-back.jpg",
"altText": "Organic Cotton Crewneck Sweater - Back"
},
{
"url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck-detail.jpg",
"altText": "Organic Cotton Crewneck Sweater - Detail"
}
],
"options": [
{
"name": "Size",
"values": [
{ "value": "S", "availableForSale": true, "exists": true },
{ "value": "M", "availableForSale": true, "exists": true },
{ "value": "L", "availableForSale": true, "exists": true }
]
}
],
"priceRange": {
"min": { "amount": "89.00", "currencyCode": "USD" },
"max": { "amount": "89.00", "currencyCode": "USD" }
},
"products": [
{
"id": "gid://shopify/Product/1111111111111",
"title": "Organic Cotton Crewneck Sweater",
"checkoutUrl": "https://ecowear-example.myshopify.com/cart/11111111111:1?_gsid=example123&payment=shop_pay",
"description": "A sustainable everyday essential. This crewneck sweater is made from certified organic cotton grown without harmful pesticides.",
"onlineStoreUrl": "https://ecowear-example.myshopify.com/products/organic-cotton-crewneck?variant=11111111111&_gsid=example123",
"price": { "amount": "89.00", "currencyCode": "USD" },
"rating": { "value": 4.8, "count": 124 },
"availableForSale": true,
"shop": {
"name": "EcoWear",
"paymentSettings": {
"supportedDigitalWallets": ["SHOPIFY_PAY"],
"acceptedCardBrands": ["visa", "master", "american_express"]
},
"onlineStoreUrl": "https://ecowear-example.myshopify.com",
"id": "gid://shopify/Shop/1111111111"
},
"selectedProductVariant": {
"id": "gid://shopify/ProductVariant/11111111111?shop=1111111111",
"availableForSale": true,
"options": [{ "name": "Size", "value": "M" }],
"price": { "amount": "89.00", "currencyCode": "USD" },
"selectionState": { "type": "match", "requestedFilters": [] }
},
"secondhand": false,
"requiresSellingPlan": false
}
],
"availableForSale": true,
"rating": { "value": 4.8, "count": 124 },
"uniqueSellingPoint": "Made from 100% certified organic cotton for eco-conscious comfort.",
"topFeatures": [
"100% organic cotton fabric provides breathable comfort",
"Relaxed fit for everyday wear",
"Ribbed cuffs and hem for a polished look",
"Classic crew neckline",
"Pre-washed for softness"
],
"techSpecs": [
"Material: 100% Organic Cotton",
"Fit: Relaxed",
"Neckline: Crew",
"Pattern: Solid",
"Color: Natural Beige",
"Available Sizes: S, M, L, XL"
],
"sharedAttributes": [
{ "name": "Neckline", "values": ["Crew"] },
{ "name": "Age group", "values": ["Adults"] },
{ "name": "Pattern", "values": ["Solid"] },
{ "name": "Fabric", "values": ["Cotton", "Organic"] },
{ "name": "Target gender", "values": ["Unisex"] },
{ "name": "Color", "values": ["Beige", "Natural"] }
],
"url": "https://discover.shopifyapps.com/global/v1/p/xyz789abc123?_gsid=example123&available_for_sale=1&ships_to=US"
},
"instructions": "Use markdown to render product titles as links to their respective product pages using the URL property."
}

Anchor to ExamplesExamples

Anchor to Lookup by variant IDLookup by variant ID

When you have a variant ID instead of a UPID, pass it directly. The response returns the Universal Product containing that variant, with the specified variant ranked first.

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "get_global_product_details",
"arguments": {
"variant_id": 43696935272470,
"context": "buyer wants details on this specific variant"
}
}
}
Anchor to Filter by product optionsFilter by product options

Narrow results to specific colors or sizes by passing an array of option key-value pairs. This example requests Blue or Navy in Medium or Large, with context about the buyer's preferences.

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "get_global_product_details",
"arguments": {
"upid": "AbC123XyZ",
"product_options": [
{ "key": "Color", "values": ["Blue", "Navy"] },
{ "key": "Size", "values": ["Medium", "Large"] }
],
"context": "buyer prefers darker colors and medium fit"
}
}
}
Anchor to Option preferences for flexible matchingOption preferences for flexible matching

Rank option importance so filters relax gracefully when exact matches aren't available. Here, color takes priority over size. If red isn't in stock, size is relaxed first.

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "get_global_product_details",
"arguments": {
"upid": "AbC123XyZ",
"product_options": [
{ "key": "Color", "values": ["Red"] },
{ "key": "Size", "values": ["Small"] }
],
"option_preferences": "Color,Size",
"context": "buyer strongly prefers red color, size is flexible"
}
}
}
Anchor to Pin a specific shop and variantPin a specific shop and variant

Use shop_id and variant_id to force a particular offer to the top of results.

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "get_global_product_details",
"arguments": {
"upid": "AbC123XyZ",
"shop_id": "gid://shopify/Shop/68817551382",
"variant_id": 43696935272470,
"include_secondhand": false
}
}
}

Anchor to Workflow exampleWorkflow example

A typical workflow combines both tools: search first, then look up details.

Anchor to Step 1: Search for productsStep 1: Search for products

Start by searching the global catalog with the buyer's query and preferences. The response includes product variants with UPIDs you can use for detailed lookups.

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "search_global_products",
"arguments": {
"query": "glossier lip balm",
"context": "buyer prefers light and bright colors",
"ships_to": "US",
"limit": 5
}
}
}
Anchor to Step 2: Get details for a specific productStep 2: Get details for a specific product

Use the UPID from search results to retrieve full product information. Add option filters to narrow down to the buyer's preferred variants.

POST

https://discover.shopifyapps.com/global/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 2,
"params": {
"name": "get_global_product_details",
"arguments": {
"upid": "AbC123XyZ",
"product_options": [
{ "key": "Color", "values": ["Cherry", "Pink"] }
],
"context": "buyer looking for subtle pink tones"
}
}
}

Anchor to Best practicesBest practices

  • Context is key: Always provide detailed context about the buyer's needs and preferences to get better results.
  • Price ranges: Use min_price and max_price in search_global_products to filter results within buyer budgets.
  • Shipping: Include ships_to for accurate shipping options and regional pricing.
  • Product options: When filtering by options, use option_preferences to specify which options are most important.
  • Availability: Set available_for_sale to true to avoid showing out-of-stock items.
  • Limit wisely: Start with reasonable limits (10-20) and increase only if needed.
  • Error handling: Check response status and provide helpful feedback to buyers.