Shopify
Shopify Storefront Catalog MCP: production checklist
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 states catalog and cart tools on the legacy MCP path were removed in favour of UCP. The April 2026 changelog entry 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 describes each tool as conforming to the UCP catalog specification, with Shopify extension fields documented separately.
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 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 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.
- Confirm which path you are shipping: Inbox agent only, or a custom integrator on UCP. If a vendor still mentions
search_shop_catalogon/api/mcp, open the migration doc and schedule retooling before June 2026 maintenance ends. - Publish an agent profile URL your integration can fetch over HTTPS. Point
meta.ucp-agent.profileat that document on every/api/ucp/mcpcall, includingtools/listduring health checks. - Run
search_catalogagainst staging with the samecatalog.context.countryandcatalog.context.currencyyour primary market uses. Compare the first page of results to predictive search on the live theme. - Exercise
get_producton your highest-variant SKU. Pass partialcatalog.selectedarrays and confirm unavailable combinations returnavailable: falseinstead of hallucinated variants. - Call
lookup_catalogwith both Product and ProductVariant GIDs pulled from Analytics or your feed. Ensurenot_foundis handled in UI copy when a discontinued SKU is referenced. - Audit product copy, metafields, and Google product category values. Agents surface description HTML and category taxonomies in structured responses. Empty descriptions become empty answers.
- 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.
- 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.
- Wire Cart MCP only after catalog IDs are stable. Create a cart with
create_cart, mutate with full payload onupdate_cart, and pass the cart id to Checkout MCP when the buyer commits. - Keep
search_shop_policies_and_faqson/api/mcpfor returns and shipping questions, but do not assume it shares caching or rate limits with UCP catalog calls. - Document internal SKUs beside variant GIDs for support staff. Agents speak GIDs; humans speak SKU on the phone.
- 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.
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.
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 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: 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.
Related work on this site
Agent shopping still depends on the same catalogue discipline as human shopping. The Ferm Living Shopify storefront and Partake Foods Shopify build are mid-catalogue stores where search quality and variant clarity already decided conversion before any bot arrived. 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 alongside this MCP note. For the WordPress side of agent-ready carts, compare WooCommerce Store API for block cart and 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.
Keep reading
Contact if you want this kind of work on a live store.