Shopify Catalog MCP guide for developers

What Shopify Catalog MCP is actually for

Shopify Catalog MCP is a product discovery interface for agentic commerce. It lets an agent search products, retrieve product details, and get enough variant information to move the buyer toward a checkout path.

The important word is discovery. Catalog MCP is not a CMS, not a theme runtime, not a full storefront replacement, and not a shortcut around product data quality. It gives agentic systems a structured way to ask commerce questions.

Shopify's agentic commerce docs describe UCP as the common language that lets agents, merchants, payment providers, and credential providers communicate consistently. Shopify provides MCP tools that implement UCP capabilities.

“Shopify provides MCP tools that are UCP-compliant to build with this interoperable and extensible protocol.”

A developer should think of Catalog MCP as the retrieval layer in a commerce agent. The agent translates buyer intent into a catalog query, receives structured product data, then decides what to show or which checkout path to open.

Global Catalog versus Storefront Catalog

Shopify currently describes two discovery models that matter for developers.

• Global Catalog: useful when the agent searches across Shopify's broader product ecosystem.

• Storefront Catalog: useful when the agent is scoped to one merchant's catalog and store policies.

Storefront Catalog MCP is the more relevant starting point for many merchant-owned use cases. If a store wants a product assistant on its own site, a post-purchase support agent, or a guided selling flow inside its own experience, the buyer has already chosen the merchant. The system needs merchant-specific product discovery, not a marketplace search.

“While Global Catalog MCP provides discovery capabilities across Shopify's entire ecosystem of stores, Storefront Catalog MCP connects to an individual merchant's catalog and store policies.”

Global Catalog is more relevant for cross-merchant shopping experiences, discovery apps, comparison surfaces, and advertising-style flows where the agent has not yet settled on a merchant.

The request and response contract

Storefront Catalog MCP exposes tools such as search_catalog, lookup_catalog, and get_product. Shopify's docs show requests sent to a merchant-domain endpoint and wrapped in a UCP metadata envelope.

The request shape matters because it tells you what the tool is meant to do:

• search_catalog answers intent like "organic coffee beans".
• lookup_catalog retrieves known products or variants by identifier.
• get_product retrieves full details for a selected product and variant state.

The context object is especially important. Shopify's docs reference buyer signals such as country, language, currency, and intent. That is where agent design becomes commerce design. A query for "winter jacket" should not behave the same for every country, budget, inventory state, or shopper intent.

Developers should preserve three boundaries:

• the agent interprets buyer language
• Catalog MCP retrieves product candidates and details
• the merchant system owns product truth and checkout rules

If those boundaries blur, the agent starts inventing commerce facts instead of retrieving them.

What Catalog MCP does not solve

Catalog MCP does not fix bad data. If the merchant's product descriptions are vague, variant names are inconsistent, or policy information is missing, the agent has less to work with.

Catalog MCP also does not replace the need for:

• durable product modeling in Shopify
• metafields and metaobjects for structured product facts
• clear product group and variant logic
• Merchant Center and structured data hygiene for Google surfaces
• checkout validation for complex business rules
• measurement and attribution conventions

This is the same lesson from normal ecommerce SEO. Search systems reward clarity. Catalog MCP gives new surfaces a way to retrieve that clarity, but the merchant still has to create it.

If a developer is building for a merchant with a messy catalog, the first milestone should be a catalog audit, not an agent demo. Use bulk operations, product exports, metafield review, and product-type analysis to find the places where the catalog cannot answer buyer questions.

How checkout handoff works

Discovery is only valuable if the buyer can move into checkout without losing context. Shopify's checkout docs for agents describe several patterns: Checkout MCP, cart permalinks, and Checkout Kit.

Checkout MCP is meant for flows that need to create and update checkout sessions, handle errors, or track checkout state. Cart permalinks are simpler: they can send a buyer directly to checkout with selected items. Checkout Kit can present Shopify checkout in a web application, popup, new tab, or embedded inline experience.

“Checkout Kit embeds the purchase flow directly in your application. Buyers stay within your application from product discovery through payment completion.”

The handoff decision should be based on flow complexity:

• Use cart permalinks for simple single-merchant product handoff.
• Use Checkout MCP when the agent needs state, errors, updates, or authentication.
• Use Checkout Kit when the app needs embedded checkout presentation.

In all cases, preserve attribution. Shopify's docs explicitly show UTM parameters appended to continuation URLs. Build that convention before production traffic arrives.

Architecture patterns that hold up

A durable agentic commerce architecture usually has five parts.

• Intent layer: translates natural language into catalog queries and constraints.

• Catalog layer: calls Global Catalog or Storefront Catalog tools and keeps product retrieval grounded.

• Merchant rules layer: checks account context, B2B constraints, preorder rules, delivery limits, discount logic, and app-specific restrictions.

• Checkout handoff layer: opens cart permalinks, Checkout MCP, or Checkout Kit with attribution.

• Observation layer: logs queries, no-result states, checkout failures, policy mismatches, and conversion outcomes.

For Rails-backed Shopify apps, keep the agent integration thin. Rails should own persisted state, merchant configuration, logging, and any calls that require app credentials. The frontend or agent surface should not become the source of truth for product logic.

The same principle appears throughout this site's developer guides: keep Shopify app boundaries explicit. If you need that shape, start with the

and the

Testing and observability

Test the agent flow with commerce scenarios, not generic prompts.

Include:

• out-of-stock products
• variant-specific price and availability
• country-specific shipping restrictions
• preorder products and mixed carts
• subscription products
• B2B-only products or prices
• products with missing images or weak descriptions
• multi-merchant results when using Global Catalog

Observability should answer four questions:

• What did the buyer ask?
• Which products did the catalog return?
• Where did the flow fail or defer?
• Did the buyer reach checkout, purchase, or contact support?

Without that loop, the team cannot tell whether weak performance comes from the model, the catalog, product data, checkout, policies, or buyer intent.

Common implementation mistakes

The common mistakes are architectural, not syntactic.

• Using Global Catalog when the buyer is already in one store. That creates unnecessary choice and weaker merchant context.

• Letting the model invent missing product facts. Missing data should produce a fallback or clarification, not a confident hallucination.

• Ignoring checkout edge cases. Bundles, subscriptions, B2B, and preorders often need extra rules.

• Shipping without attribution. Agentic traffic can look like direct or generic referral traffic if URLs are not tagged.

• Skipping merchant controls. Merchants need configuration, preview, logs, and a way to disable risky surfaces.

The reliable pattern is retrieval first, commerce rules second, checkout third, measurement always.

Best internal links

• Shopify agentic commerce readiness guide

  for the merchant and operator view.

• Shopify UCP readiness for merchants

  for protocol implications without developer overload.

• Shopify AI shopping product data guide

  for the catalog-quality layer.

• Checkout UI Extensions with a custom backend architecture

  for checkout-adjacent backend patterns.

Sources and further reading

• Shopify Dev: Agentic commerce

• Shopify Dev: About Catalogs

• Shopify Dev: Storefront Catalog MCP

• Shopify Dev: Checkout for agents

• Shopify Dev: Checkout Kit for Web