--- title: Catalog MCP server description: >- Use the Catalog MCP server to search for products across the global Shopify ecosystem. source_url: html: 'https://shopify.dev/docs/agents/catalog/catalog-mcp' md: 'https://shopify.dev/docs/agents/catalog/catalog-mcp.md' --- # 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. ## How 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](https://shopify.dev/docs/agents/catalog#usage-guidelines). For the UCP protocol overview, see [Core concepts](https://ucp.dev/documentation/core-concepts/). ## Authenticate Obtain your client credentials (client ID and secret) from [the **Catalog** section of Dev Dashboard](https://shopify.dev/docs/apps/build/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 ```bash 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 will contain: * `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`](https://www.jwt.io/) to investigate more details related to how Shopify issues this token. ## {} Response ```json { "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: ```text https://discover.shopifyapps.com/global/mcp ``` Learn more about [building agentic commerce experiences](https://shopify.dev/docs/agents/get-started/authentication). POST ## https://discover.shopifyapps.com/global/mcp ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "tool_name", "arguments": { // tool-specific arguments } } } ``` ## Available tools Catalog MCP provides core tools for product discovery across all of Shopify: * [`search_global_products`](#search_global_products): Search for products across all Shopify merchants based on buyer queries and preferences. * [`get_global_product_details`](#get_global_product_details): Retrieve detailed information about a specific product using its Universal Product ID (UPID) or a variant ID. ### `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](https://shopify.dev/docs/api/catalog-api/search), which can also be used depending on your use case. #### Parameters context•stringRequired (critical) Additional information about the request such as user demographics, mood, location, or other relevant details that could help tailor the response. query•stringRequired (critical) 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](https://shopify.dev/docs/agents/catalog#saved-catalogs). 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](https://www.iso.org/iso-3166-country-codes.html)). ships\_to•string Filter by shipping destination ([ISO country code](https://www.iso.org/iso-3166-country-codes.html)). shop\_ids•array Array of shop IDs to filter by specific shops. POST ## https://discover.shopifyapps.com/global/mcp ```json { "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 ```json { "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." } ``` #### Examples ##### Use 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 ```json { "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 } } } ``` ##### Subscription 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 ```json { "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 } } } ``` ##### Secondhand 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 ```json { "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 } } } ``` ### `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`](https://shopify.dev/docs/api/catalog-api/lookup) and [`Lookup by variant`](https://shopify.dev/docs/api/catalog-api/lookup-by-variant) endpoints of Catalog API, which can also be used depending on your use case. #### Parameters upid•stringRequired\* (critical) The Universal Product ID (in Base62 encoded format). Required if `variant_id` is not provided. variant\_id•integerRequired\* (critical) A Shopify variant ID. Required if `upid` is not 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). max\_price•number Maximum price the buyer is willing to pay. min\_price•number Minimum price the buyer is willing to pay. 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](https://www.iso.org/iso-3166-country-codes.html)). ships\_to•string Filter by shipping destination ([ISO country code](https://www.iso.org/iso-3166-country-codes.html)). shop\_id•string Filter by specific shop (numeric ID or Shop GID). POST ## https://discover.shopifyapps.com/global/mcp ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "get_global_product_details", "arguments": { "upid": "AbC123XyZ" } } } ``` ## {} Response ```json { "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." } ``` #### Examples ##### Lookup 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 ```json { "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" } } } ``` ##### Filter 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 ```json { "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" } } } ``` ##### Price range and shipping Combine price bounds with shipping destination to find offers within budget that can be delivered to the buyer's location. POST ## https://discover.shopifyapps.com/global/mcp ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "get_global_product_details", "arguments": { "upid": "AbC123XyZ", "min_price": 20, "max_price": 100, "ships_to": "GB", "available_for_sale": true, "limit": 20 } } } ``` ##### Option 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 ```json { "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" } } } ``` ##### Pin 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 ```json { "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 } } } ``` ## Workflow example A typical workflow combines both tools: search first, then look up details. ##### Step 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 ```json { "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 } } } ``` ##### Step 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 ```json { "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" } } } ``` ## Best 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` 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.