UCP, Storefront MCP and Your Catalog: Getting a Shopify Store Agent-Ready

In April 2026, developers on Shopify's community forum started reporting that their shopping assistants had stopped finding products. Calls to search_shop_catalog, the Storefront MCP tool for searching a store's products, began returning Tool not found. It had been replaced by search_catalog, on a different endpoint, with a new input schema.

That is a small incident and a useful one. The layer AI agents use to shop on Shopify is still moving, and getting a store agent-ready isn't a setting you flip. It means knowing which of three layers you depend on, and which parts of your own catalogue decide whether an agent can sell anything at all.

Three layers, one catalogue

Shopify Catalog is the syndication layer. Eligible products are made discoverable to AI channels, which Shopify currently lists as ChatGPT, Google AI Mode and Gemini, Microsoft Copilot and Meta, with their title, description, options, images, price and availability. Shopify says it keeps inventory and pricing updated continuously across those channels. For most merchants this is the whole integration: nothing to build, but nothing to tune either, except the data you feed it.

Storefront MCP is the per-store interface. A Shopify store exposes an MCP server that an agent can call directly, without authentication, using JSON-RPC 2.0 over HTTP POST. This is what a custom assistant, or any agent that talks to your store rather than to a marketplace, actually uses.

The Universal Commerce Protocol (UCP) is the contract underneath. Shopify and Google co-developed it as an open standard for how agents discover products, negotiate what a merchant supports and run checkout. Merchants and agents publish profiles at /.well-known/ucp, each side declares its capabilities, and the session runs on the intersection. Checkout, orders and catalogue are separate capabilities, each versioned on its own.

The practical point for a technical lead: the first layer is Shopify's job, the second and third are contracts you may be coding against, and contracts at this stage change.

What an agent actually calls

Storefront MCP is now split across two endpoints on your store's domain:

• https://{shop}.myshopify.com/api/ucp/mcp carries the UCP catalogue tools: search_catalog, lookup_catalog (up to 10 ids per call) and get_product.
• https://{shop}.myshopify.com/api/mcp carries the rest: search_shop_policies_and_faqs, get_cart and update_cart.

The UCP tools expect an agent profile in every request and wrap their arguments in a catalog object. This is the shape from Shopify's documentation:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "query": "organic coffee beans",
        "context": { "address_country": "US", "intent": "Customer prefers fair trade products" }
      }
    }
  }
}

If you wrote an agent against the older flat search_shop_catalog call, the April change is exactly what broke it. The fix is small; the lesson is to treat the tool list as something you discover at runtime (tools/list is part of MCP), pin behaviour behind your own adapter, and alert on Tool not found rather than on empty results.

Checkout is a state machine, not a redirect

UCP models checkout as a session that moves through states, including incomplete, requires_escalation and ready_for_complete. When the merchant needs something only a person can provide, the session escalates and returns a continue_url; the buyer follows it and, in Shopify's words, "picks up exactly where the agent left off" in an embedded checkout.

That changes what you test. The question is not whether an agent can reach your checkout, but which of your checkout rules push a session into escalation: custom validation, required fields your storefront adds, logic that lives in a theme rather than in the platform. Every escalation is a hand-off from a conversation to a web page, and some buyers won't make it across. Walk your real checkout through the agent path and list what escalates before you promise anyone "buy inside ChatGPT".

The catalogue work that decides whether agents can sell

Most of the effort sits here, and none of it is new code.

Eligibility. Shopify Catalog only includes products with a title, at least one image and a price above zero, published to the online store, Hydrogen or a headless channel. Agentic storefronts also need an external product URL for each product, stored in the external URL standard metafield. A product that fails any of these is invisible to agents, however good it is.

Structure. Shopify's own guidance is to group genuine variants under one parent, so an agent understands one product with options rather than twelve near-duplicates, and to use the most specific category available: "men's insulated winter boots", not "footwear". It also asks for literal descriptions. Marketing copy that works on a landing page gives a language model very little to match against.

Data that lives in the wrong place. Plenty of mature stores keep real attributes in tag prefixes, metafields, metaobjects or split titles. Shopify Catalog Mapping exists for exactly this: it points the catalogue at where your data actually lives. If your size, material or compatibility data is in a tag like size:42, map it before assuming agents can see it.

B2B separation. Agentic storefronts are for direct-to-consumer sales. Shopify excludes B2B-only products it can identify through B2B catalogues, customer account requirements or password-protected storefronts, but a custom B2B implementation may need products hidden by hand, by setting them to Unlisted. A store that mixes trade and retail pricing through its own logic should check what agents are actually offered.

Stock you can promise. Shopify's line is that price and inventory "need to be accurate at the moment of the shopper's query". If stock is mastered in an ERP or WMS and synced to Shopify on a schedule, the agent sells from the last sync. On a busy day that is the difference between an order and a cancellation, and an agent-driven cancellation is a worse experience than a normal one, because the buyer never saw your store.

A readiness pass, in order

1. Run an eligibility report over the catalogue: no image, zero price, missing external URL, unpublished to the right channel. Fix these first; they are binary.
2. Map your data. List every attribute that lives in tags or metafields and set up Catalog Mapping for it.
3. Collapse false variants into single products with options, and tighten categories.
4. Decide what agents must not sell, especially trade-only items, and set them to Unlisted if Shopify can't detect them.
5. Measure your stock lag. How long between a change in the system that owns inventory and the same change in Shopify? If the answer is minutes, fix the sync before you invite agents in.
6. Walk checkout through the agent path and list every rule that escalates.
7. If you run your own agent, wrap the MCP calls behind an adapter, discover tools at runtime and alert on renamed or missing tools.

Shopify reports that AI-referred orders grew nearly 13x year over year. An agent buying on a shopper's behalf never sees your theme. What it sees is your catalogue data, so that is where the work goes.

If you would rather go through this against your own catalogue and integrations, talk to us.

---

Verified against Shopify's Storefront MCP documentation, the Shopify Engineering post on UCP, the Help Center pages on agentic storefronts and catalogue product discovery, Shopify's guide to agentic-ready product data, and the community thread on the tool rename, in September 2026.