---
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/mcp'
  md: 'https://shopify.dev/docs/agents/catalog/mcp.md'
---

ExpandOn this page

* [How it works](https://shopify.dev/docs/agents/catalog/mcp.md#how-it-works)
* [Authenticate](https://shopify.dev/docs/agents/catalog/mcp.md#authenticate)
* [Create an API request to the Catalog MCP server](https://shopify.dev/docs/agents/catalog/mcp.md#create-an-api-request-to-the-catalog-mcp-server)
* [Available tools](https://shopify.dev/docs/agents/catalog/mcp.md#available-tools)
* [Workflow example](https://shopify.dev/docs/agents/catalog/mcp.md#workflow-example)
* [Best practices](https://shopify.dev/docs/agents/catalog/mcp.md#best-practices)

# Catalog MCP server

Early access

Agentic commerce is rolling out to Dev Dashboard. [Sign up to be notified](https://docs.google.com/forms/d/e/1FAIpQLSe4DsRrfytH6CBrolSJdPKLyl-e-K2MEBDOjm-F-ZJpNy6Vtw/viewform).

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.

Tip

For usage guidelines, see [About Catalog](https://shopify.dev/docs/agents/catalog#usage-guidelines).

***

## Authenticate

Obtain a bearer token from Shopify, which you can use for all subsequent MCP server requests.

### Generate a bearer token from an API key

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:

## Terminal

```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"
  }'
```

Set the token in your environment:

## Terminal

```bash
export BEARER_TOKEN={your_token}
```

All requests require the `Authorization: Bearer {token}` header.

***

## Create an API request to the Catalog MCP server

All requests follow the JSON-RPC 2.0 protocol. Send POST requests to:

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

Request format:

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

***

## Available tools

The Catalog MCP server provides two core tools for product discovery.

### `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"

Key parameters:

| Parameter | Type | Description |
| - | - | - |
| `context` | string | Required Additional information about the request such as user demographics, mood, location, or other relevant details that could help tailor the response. |
| `query` | string | Required 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` | integer | Maximum number of products to return (1-300, default: 10). |
| `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). |
| `requires_selling_plan` | boolean | When `true`, include only subscription products. When `false`, include only non-subscription products. |
| `ships_from` | string | Filter by shipping origin (ISO country code). |
| `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. |

Response includes:

* A list of matching products.
* Product titles, descriptions, and images.
* Pricing information.
* Shop information.
* Product variants.
* Universal Product IDs (UPID) for detailed lookups.

Example (basic search):

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_global_products",
    "arguments": {
      "query": "running shoes",
      "context": "buyer looking for comfortable athletic shoes for daily jogging",
      "limit": 10
    }
  }
}
```

Example (with price and shipping filters):

```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
    }
  }
}
```

Example (subscription products):

```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
    }
  }
}
```

Example (secondhand products):

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

Use this tool when a buyer is asking about a specific product and you have the product 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.

Key parameters:

| Parameter | Type | Description |
| - | - | - |
| `upid` | string | Required• The Universal Product ID (in Base62 encoded format). |
| `_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, instead of excluding them. |
| `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` | integer | Maximum number of offers to return for the product (1-100, default: 10). |
| `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). |
| `ships_to` | string | Filter by shipping destination (ISO country code). |
| `shop_id` | string | Filter by specific shop (numeric ID or Shop GID). |
| `variant_id` | integer | Force this variant to be the first result. |

Response includes:

* Complete product information.
* All available variants with pricing.
* Product options (colors, sizes, and so on).
* Shop details and branding.
* Availability status.
* Shipping information.
* Images and descriptions.

Example (basic lookup):

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

Example (with product options filter):

```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"
    }
  }
}
```

Example (with price range and shipping):

```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
    }
  }
}
```

Example (with option preferences):

```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"
    }
  }
}
```

Example (specific shop and variant):

```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:

1. Step 1: Search for products

   ```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
       }
     }
   }
   ```

   The response includes product variants with UPIDs.

2. Step 2: Get details for a specific product

   Use the variant UPID from search results to perform a Lookup:

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

***

* [How it works](https://shopify.dev/docs/agents/catalog/mcp.md#how-it-works)
* [Authenticate](https://shopify.dev/docs/agents/catalog/mcp.md#authenticate)
* [Create an API request to the Catalog MCP server](https://shopify.dev/docs/agents/catalog/mcp.md#create-an-api-request-to-the-catalog-mcp-server)
* [Available tools](https://shopify.dev/docs/agents/catalog/mcp.md#available-tools)
* [Workflow example](https://shopify.dev/docs/agents/catalog/mcp.md#workflow-example)
* [Best practices](https://shopify.dev/docs/agents/catalog/mcp.md#best-practices)