# Shopify Storefront Catalog MCP: production checklist

UCP catalog tools on /api/ucp/mcp, agent profiles, search_catalog, and how live Shopify data feeds agent shopping in 2026.

- Date: 2026-10-03
- Category: Shopify

## Table of contents

- Why Shopify Storefront Catalog MCP changed in 2026
- How Shopify Storefront Catalog MCP works on one store
- Production checklist before you enable agent shopping
- What breaks when Shopify Storefront Catalog MCP meets a messy catalogue
- How I measure Shopify Storefront Catalog MCP on a live store
- Related work on this site
- FAQ
  - What is Shopify Storefront Catalog MCP used for?
  - Do I need an agent profile for Shopify Storefront Catalog MCP?
  - How does Shopify Storefront Catalog MCP relate to Cart MCP?
  - Will Shopify Storefront Catalog MCP fix weak product SEO?

Shopify Storefront Catalog MCP is how an AI agent searches one merchant catalogue without scraping your theme HTML. I am Alan Vo, a Gold Coast web developer with 18 years of storefront work. In 2026 the old Storefront MCP catalog tools moved to Universal Commerce Protocol (UCP) on `https://{shop-domain}/api/ucp/mcp`. If you ship Shopify Plus or mid-market catalogues, this endpoint is the contract between your product data and every inbox agent, custom assistant, or partner bot a client wants to turn on.

This note is for production teams, not a sample-app tutorial. I care whether search results match what humans see on the PDP, whether variant availability survives a colour switch, and whether the cart handoff still lands in Shopify checkout. The theme still owns the buyer journey for most traffic. Storefront Catalog MCP is the read model agents use when they skip the grid.

## Why Shopify Storefront Catalog MCP changed in 2026

Shopify Storefront Catalog MCP changed because Shopify aligned agent commerce with UCP instead of bespoke JSON shapes on `https://{shop}/api/mcp`. Shopify's [migration guide](https://shopify.dev/docs/apps/build/storefront-mcp) states catalog and cart tools on the legacy MCP path were removed in favour of UCP. The April 2026 [changelog entry](https://shopify.dev/changelog/storefront-catalog-mcp-now-implements-ucp) renamed tools to `search_catalog`, `lookup_catalog`, and `get_product`, pointed integrators at `/api/ucp/mcp`, and set a maintenance window for older tool names through mid-June 2026.

That matters on live stores for three reasons. First, any partner still calling `get_product_details` on the old endpoint will return errors after sunset, even when the storefront looks fine. Second, every UCP call must carry `meta.ucp-agent.profile` with a URL to your agent's profile document. Missing profile metadata is not a soft warning. The server expects the envelope on `tools/list` and `tools/call`. Third, catalog search is now explicitly scoped to one merchant. Cross-store discovery is a different surface (Global Catalog MCP). Your merchandising and SEO work still decide what that single-store index contains.

Merchants who only want chat on the Online Store without custom code are steered toward the Inbox agent in Shopify Inbox, per the same migration doc. Developers building third-party assistants are steered toward UCP. I still write this for the developer path because agency and in-house teams ask me to validate catalog quality before they flip an agent on.

## How Shopify Storefront Catalog MCP works on one store

Shopify Storefront Catalog MCP exposes three JSON-RPC tools on the merchant's UCP endpoint: `search_catalog`, `lookup_catalog`, and `get_product`. Shopify's [Storefront Catalog MCP documentation](https://shopify.dev/docs/agents/catalog/storefront-catalog) describes each tool as conforming to the UCP catalog specification, with Shopify extension fields documented separately.

![Shopify Storefront Catalog MCP on a laptop showing a Shopify storefront layout](../../images/blog/shopify-storefront-catalog-mcp-1.jpg)

`search_catalog` accepts a free-text `catalog.query`, optional buyer `catalog.context` (country, language, currency, intent string), and cursor pagination with default limit 10 and max 250. Responses include product title, description, price range in minor units, media, variants, categories, and pagination cursors. That is the agent equivalent of storefront search, not Admin API bulk export.

`lookup_catalog` resolves up to ten product or variant GIDs in one call. I use it to refresh prices and availability after a long conversation, or to validate IDs returned from a deep link before Cart MCP runs. Unresolved IDs come back as structured `not_found` messages rather than silent omission.

`get_product` returns full PDP-grade detail for one product or variant ID, with optional `catalog.selected` option pairs such as Colour and Size. The response includes option values annotated with `available` and `exists` signals, plus a `product.selected` array reflecting the effective variant narrowing. That mirrors what a theme option picker must compute, which is why bad option order in admin shows up in agents first.

The [Storefront MCP server overview](https://shopify.dev/docs/apps/build/storefront-mcp/servers/storefront) splits endpoints deliberately. UCP catalog tools live on `/api/ucp/mcp`. Legacy storefront tools such as `get_cart`, `update_cart`, and `search_shop_policies_and_faqs` remain on `/api/mcp` without the agent profile requirement on the policy search path documented there. Cart creation and mutation moved to [Cart MCP](https://shopify.dev/docs/agents/carts-and-checkout/cart-mcp) on the UCP endpoint with capability version `2026-08-25`. Each `update_cart` replaces the entire cart, so integrators must resend every line item they intend to keep.

Catalog MCP does not authenticate the buyer. Cart MCP also accepts unauthenticated requests for estimation and sharing via `continue_url`. Checkout conversion is yet another MCP surface. Production work therefore spans three contracts: catalogue truth, cart state, and signed checkout creation. A theme-only QA pass misses two of them.

## Production checklist before you enable agent shopping

The production checklist starts with catalogue hygiene, because agents quote whatever Shopify indexes.

1. Confirm which path you are shipping: Inbox agent only, or a custom integrator on UCP. If a vendor still mentions `search_shop_catalog` on `/api/mcp`, open the migration doc and schedule retooling before June 2026 maintenance ends.
2. Publish an agent profile URL your integration can fetch over HTTPS. Point `meta.ucp-agent.profile` at that document on every `/api/ucp/mcp` call, including `tools/list` during health checks.
3. Run `search_catalog` against staging with the same `catalog.context.country` and `catalog.context.currency` your primary market uses. Compare the first page of results to predictive search on the live theme.
4. Exercise `get_product` on your highest-variant SKU. Pass partial `catalog.selected` arrays and confirm unavailable combinations return `available: false` instead of hallucinated variants.
5. Call `lookup_catalog` with both Product and ProductVariant GIDs pulled from Analytics or your feed. Ensure `not_found` is handled in UI copy when a discontinued SKU is referenced.
6. Audit product copy, metafields, and Google product category values. Agents surface description HTML and category taxonomies in structured responses. Empty descriptions become empty answers.
7. If you use Combined Listings on Plus, decide which product GIDs agents should treat as canonical. Child products remain the sellable records. Parent products group options. An agent that adds the parent ID to Cart MCP will fail checkout rules you already enforce on the theme.
8. Walk Markets and B2B catalogs if you expose them on the same domain. Context fields are signals, not guarantees. Verify price ranges in the response against the storefront for each market you care about.
9. Wire Cart MCP only after catalog IDs are stable. Create a cart with `create_cart`, mutate with full payload on `update_cart`, and pass the cart id to Checkout MCP when the buyer commits.
10. Keep `search_shop_policies_and_faqs` on `/api/mcp` for returns and shipping questions, but do not assume it shares caching or rate limits with UCP catalog calls.
11. Document internal SKUs beside variant GIDs for support staff. Agents speak GIDs; humans speak SKU on the phone.
12. Add monitoring on JSON-RPC error codes and latency per shop domain. A theme deploy does not move these endpoints, but app installs and catalog bulk edits do change response times.

![Clothing rails in a shop used as a live catalogue for Shopify Storefront Catalog MCP](../../images/blog/shopify-storefront-catalog-mcp-2.jpg)

## What breaks when Shopify Storefront Catalog MCP meets a messy catalogue

Stale integrations are the first break. Teams that copied 2025 sample code calling deprecated tool names against `/api/mcp` see hard failures while the Online Store checkout still converts. The fix is endpoint plus tool rename, not a theme rollback.

Missing agent profiles are the second break. UCP requests without `meta.ucp-agent.profile` fail before catalog logic runs. I have seen staging keys work on `/api/mcp` policy search and falsely assume catalog would behave the same way.

Partial cart updates are the third break. Cart MCP replaces the whole cart on `update_cart`. An agent that sends only the newly added line deletes earlier items. That looks like a malicious bug to shoppers even when the catalog tools behaved perfectly.

![Theme code on a monitor during Shopify Storefront Catalog MCP work](../../images/blog/shopify-storefront-catalog-mcp-3.jpg)

Catalogue drift is the fourth break. Draft products, wrong availability on one market, or combined listing parents treated as purchasable SKUs produce confident agent answers that the theme contradicts. The API is honest about availability flags, but it cannot fix merchandising mistakes.

SEO and faceted navigation mismatches are the fifth break. If Search and Discovery hides a colour child while the feed still advertises it, `lookup_catalog` may resolve the variant while collection pages hide it. Agents do not read your robots.txt story. They read indexed catalog data.

Rate and pagination misuse is the sixth break. Pulling max `limit` 250 on every conversational turn is expensive and unnecessary. Cursor pagination exists so agents can walk large result sets without pretending to be a human scrolling one page.

Theme checkout extensibility is the seventh break, but it sits downstream. Shopify's [checkout extensibility deadlines](https://alanvo.com/blog/shopify-checkout-extensibility/) still govern how the human finishes payment after an agent hands off a checkout URL. Catalog MCP does not replace pixel or Functions work. It feeds the top of the funnel.

## How I measure Shopify Storefront Catalog MCP on a live store

I measure Shopify Storefront Catalog MCP with contract tests, parity checks, and funnel attribution, in that order.

Contract tests hit `/api/ucp/mcp` from CI with a fixed agent profile and record JSON-RPC schemas for the three catalog tools. I snapshot hash the `structuredContent.ucp.version` field and a handful of product IDs so unintended Admin changes trigger review before marketing enables a new agent.

Parity checks compare ten intentional queries: five bestsellers, two long-tail searches, two out-of-stock variants, and one combined listing colour switch. For each query I log theme search or PDP price against `search_catalog` or `get_product` minor-unit amounts and currency. Mismatch over one cent triggers a catalog ticket, not an agent ticket.

Funnel attribution stays separate. Web pixels and GA4 still belong on the human path. When Cart MCP emits a `continue_url`, I tag those sessions in analytics with a dedicated UTM or custom dimension so paid media does not double-count agent-assisted revenue against ordinary checkout. I do not invent conversion lift from agent launches. The published figure I will cite remains the [Their Nibs Shopify rebuild](https://alanvo.com/work/their-nibs/): 31% more conversions and 48% more orders after purchase-path work on the theme and checkout, not from MCP.

Operational metrics include p95 latency for `search_catalog`, error rate on `lookup_catalog` `not_found`, and cart abandonment after agent handoff versus mobile web baseline. Spikes after large imports usually mean incomplete variant publication, not MCP regression.

![Phone showing a product page in Shopify Storefront Catalog MCP testing](../../images/blog/shopify-storefront-catalog-mcp-4.jpg)

## Related work on this site

Agent shopping still depends on the same catalogue discipline as human shopping. The [Ferm Living Shopify storefront](https://alanvo.com/work/ferm-living/) and [Partake Foods Shopify build](https://alanvo.com/work/partake-foods/) are mid-catalogue stores where search quality and variant clarity already decided conversion before any bot arrived. [Their Nibs](https://alanvo.com/work/their-nibs/) is the case where checkout and merchandising had to agree under pressure. If you are untangling parent and child products for Plus, read [Shopify Combined Listings on production catalogues](https://alanvo.com/blog/shopify-combined-listings/) alongside this MCP note. For the WordPress side of agent-ready carts, compare [WooCommerce Store API for block cart and checkout](https://alanvo.com/blog/woocommerce-store-api-cart-checkout/), which solves a similar handoff with cart tokens instead of UCP.

## FAQ

### What is Shopify Storefront Catalog MCP used for?

Shopify Storefront Catalog MCP lets an AI agent search and read one Shopify store's product catalogue over MCP using UCP tools on `/api/ucp/mcp`. Use it when buyer intent stays on a single merchant domain. Use other surfaces when you need cross-store discovery or when the merchant only wants Shopify Inbox chat without custom integration.

### Do I need an agent profile for Shopify Storefront Catalog MCP?

Yes. Every request to `/api/ucp/mcp` must include `meta.ucp-agent.profile` pointing to your agent's UCP profile URL. That includes listing tools during health checks. Policy and FAQ search on `/api/mcp` follows the separate Storefront MCP server rules documented by Shopify.

### How does Shopify Storefront Catalog MCP relate to Cart MCP?

Shopify Storefront Catalog MCP returns product and variant identifiers and availability. Cart MCP on the same UCP endpoint creates and mutates carts from those identifiers, then Checkout MCP converts an approved cart into payment. Catalog responses do not hold cart state. Treat them as sequential steps in agent design.

### Will Shopify Storefront Catalog MCP fix weak product SEO?

No. Shopify Storefront Catalog MCP exposes the catalogue Shopify already indexes. Thin titles, missing descriptions, and conflicting combined listing parents still produce weak agent answers. Fix merchandising, Search and Discovery settings, and market publishing first, then re-run parity checks against `search_catalog` and `get_product`.


![Card payment at a counter after a Shopify Storefront Catalog MCP release](../../images/blog/shopify-storefront-catalog-mcp-5.jpg)


HTML version: https://alanvo.com/blog/shopify-storefront-catalog-mcp/