Global Catalog MCP

Free-text search query. For example, "trail running shoes", "organic coffee beans".

Slug for a saved catalog configuration created in the Dev Dashboard. Saved filters act as a boundary for the request: a request value within the boundary is narrowed, and a value outside the boundary falls back to the saved value. A saved query prefix is prepended to catalog.query at request time, so the prefix and the request query are combined rather than one replacing the other.

Similar item to search by. Use either an item reference or image content.

Pass both catalog.query and an image in catalog.like for multimodal search. Multimodal search uses the text query to describe what the agent is looking for and the image to provide visual context, such as style, shape, or pattern. Pass only an image for visual similarity search, which returns items that visually resemble the image without additional text intent.

Buyer signals for relevance and localization (address_country, address_region, postal_code, language, currency, and intent).

Filter by availability. Defaults to true (only sale-ready items). Set to false to include unavailable items.

Filter to products that ship to a given location. Accepts country (ISO 3166-1 alpha-2), region, and postal_code.

Filter by merchant origin country. Each entry accepts country (ISO 3166-1 alpha-2). Multiple entries use OR logic. Digital products that don't require shipping can still match this filter.

Price range in minor currency units. Accepts min and max integers. For example, {"min": 5000, "max": 20000} = $50.00–$200.00 USD.

Product condition filter. Known values: "new", "secondhand". Multiple values use OR logic.

Filter to specific shops. Accepts an array of shop GIDs, for example gid://shopify/Shop/987654321. You can pass up to 1000 shop IDs per request.

Filter by Shopify taxonomy attributes. Supported names are Color, Size, and Target gender. Entries combine with AND logic. Values within one entry combine with OR logic. Unsupported attribute names are ignored and returned in messages.

Filter by variant rating. variant matches products with at least one variant whose rating meets the given thresholds. Set variant.min for the minimum rating value (0–5 scale) and variant.min_count for the minimum number of reviews.

Filter by relative price tier within each product's category. Supported values are low, medium, and high. Multiple values use OR logic. Unsupported values are ignored and returned in messages.

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.

Predefined output shape for the response. Use "offer" for comparison shopping. When absent, the server returns its default shape.

Optional promoted placement types to blend into the response.

Each value is an open string that matches a placement.type. When you set this to ["affiliate"], Shopify re-ranks results using both promoted placement eligibility and relevance, then returns promoted placements inline with organic results. When you omit this field or pass an empty array, Shopify returns only organic results ranked by relevance.

The only well-known value is "affiliate", which represents affiliate promoted placements where you earn a commission when a click converts to a purchase.

Cursor-based pagination controls. Accepts cursor (string, opaque cursor from a previous response) and limit (integer, min 1, default 10, max 50). Pass the returned pagination.cursor as catalog.pagination.cursor to request the next page. The cursor carries only the next result offset, so the request's limit controls page size. You can paginate up to 1,000 results. Beyond that depth, has_next_page is false regardless of how many results match.

The total_count field in the response is an estimate of how many results match the query, not an exact count. Don't rely on it for precise totals or to calculate an exact number of pages.

Array of product or variant identifiers (1 to 50). Accepts gid://shopify/p/{upid}, gid://shopify/ProductVariant/{id}, and http or https Shopify product URLs. Multiple IDs that resolve to the same product are grouped into a single product in the response.

Filter to products that ship to a given location. Accepts country, region, and postal_code.

Filter by merchant origin country. Each entry accepts country (ISO 3166-1 alpha-2). Multiple entries use OR logic. Digital products that don't require shipping can still match this filter.

Filter by availability. Defaults to true (only sale-ready items). Set to false to include unavailable items.

Product condition filter. Known values: "new", "secondhand". Multiple values use OR logic.

Buyer context for localization (address_country, address_region, postal_code, language, currency, and intent).

Predefined output shape for the response. Use "offer" for comparison shopping. When absent, the server returns its default shape.

Product or variant identifier. Accepts gid://shopify/p/{upid} or gid://shopify/ProductVariant/{id}.

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.

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.

Filter to products that ship to a given location. Accepts country, region, and postal_code.

Filter by merchant origin country. Each entry accepts country (ISO 3166-1 alpha-2). Multiple entries use OR logic. Digital products that don't require shipping can still match this filter.

Filter by availability. Defaults to true (only sale-ready items). Set to false to include unavailable items.

Product condition filter. Known values: "new", "secondhand". Multiple values use OR logic.

Buyer context for localization (address_country, address_region, postal_code, language, currency, and intent).

Predefined output shape for the response. Use "summary" for a condensed product detail view. When absent, the server returns its default shape.