Skip to content
Universal Commerce Protocol Universal Commerce Protocol Protocol registry / en
The UCP standardUCP vs ACPImplementAgentic commerceFramework
ConceptGEOllms.txtGlossaryAgentic paymentsAP2Visa and MastercardB2B agentic commerceMethodologyUse CasesWhy NowFor WhomManifestoFAQResourcesSourcesEcosystemValidatorReadiness diagnosticAboutContact
FR Run the diagnostic →

Reference note

Shopify agents.md, Catalog MCP, Cart MCP, and UCP

Understand Shopify's agent surfaces: discovery, product truth, Catalog MCP, UCP carts, WebMCP, and checkout.

Published , revised . Part of the UCP and MCP comparison.

Shopify exposes several surfaces to agents. They answer different questions and should not be tested as one object. Discovery files describe the store. Shopify Catalog holds structured product data. Catalog MCP supports product search and retrieval. Cart MCP holds cart state. WebMCP acts in the shopper’s tab, while checkout remains the authorization boundary.

Key takeaways

  • /agents.md, /llms.txt, and /llms-full.txt describe the store.
  • Shopify Catalog and Catalog MCP make product facts available to channels and agents.
  • UCP Cart MCP and WebMCP manipulate distinct states. Neither proves on its own that a purchase is complete.

This distinction extends the UCP vs MCP comparison: UCP describes commerce, while MCP can provide the interface used to invoke structured tools.

What do Shopify’s discovery files prove?

Shopify automatically serves /agents.md, /llms.txt, and /llms-full.txt. Within Shopify, /agents.md is the canonical agent-discovery URL. The two llms paths provide compatibility for crawlers that look for those conventions. All three serve the same content by default.

These files can identify the store, its URL, sitemap, and public policies. They do not replace the product catalog, permissions, or checkout. Their presence also does not guarantee that a product will appear or rank.

Where does structured product truth live?

Shopify Catalog gathers eligible products and sends structured fields to agentic channels. Shopify describes it as the authoritative feed for those data. That authority covers the facts Shopify sends, not the final channel’s decision. Inclusion does not guarantee an appearance, a position, or availability in every channel.

A useful audit compares the product page, structured data, Shopify Catalog, store policies, and the checkout response. A price or availability mismatch matters more than a wording difference in a discovery file.

Why do these three names refer to different layers?

Shopify documents two catalog interfaces, Global Catalog and Storefront Catalog. Both implement the UCP Catalog capability and expose the same three tools. The WebMCP documentation instead describes tools registered with the browser to act on the page the shopper is viewing.

Surface Where does it run? Primary role
UCP merchant and platform contract define commerce capabilities
Catalog MCP remote Shopify or storefront server search and resolve products
WebMCP shopper’s browser tab read and change the current session

The decisive difference is the execution surface. A remote agent comparing several merchants does not share the context of an assistant running inside a store tab. One architecture can use several surfaces as long as it does not conflate their states.

What exactly does UCP provide?

UCP supplies the vocabulary and rules for agentic commerce. The protocol organizes merchant profile discovery, capability negotiation, and the Catalog, Cart, Checkout, and Orders services. It supports several transports, including REST, MCP, A2A, and an embedded protocol.

An operation exposed as an MCP tool can therefore remain compliant with a UCP capability. MCP tells the agent how to invoke the tool. UCP defines the commercial meaning of its objects, expected states, and compatibility rules. The UCP implementation guide details this merchant-side negotiation.

UCP does not replace the storefront interface. The protocol also supports browserless flows in which a platform orchestrates a remote purchase. The web page remains useful to the shopper, but it is not the only possible entry point.

What does Catalog MCP provide on Shopify?

Shopify documents two scopes. Global Catalog searches across eligible Shopify merchants. Storefront Catalog restricts results to one shop. Both implement UCP’s Catalog capability and use agent-profile authentication, with no API key required for the documented requests.

The three tools serve different intents:

  1. search_catalog answers a natural-language product request;
  2. lookup_catalog refreshes data for products or variants already identified;
  3. get_product loads one product’s details and option combinations.

Shopify also documents different lookup_catalog limits: up to 50 identifiers for Global Catalog and 10 for Storefront Catalog. Results and images must not be cached. Some fields can be inferred by Shopify systems and are marked with an Inferred label in the reference documentation.

The GEO-readable catalog guide explains how to prepare product data without breaking identifier continuity.

How does WebMCP change the storefront experience?

WebMCP serves agents that shoppers bring into their browsers. Shopify provides the tools on every Liquid storefront and on Hydrogen storefronts in developer preview. The current documentation says merchants do not need to install or configure them, while agent support remains limited to Chromium-based browsers.

The tools act on the visible session. A cart update changes the cart the shopper sees. A navigation action opens the corresponding page. When the theme connects its standard cart action to a drawer, the agent triggers that same theme behavior.

The reference lists ten tools across catalog, cart, checkout, orders, and store information. They include search_catalog, browse_store, get_product, update_cart, proceed_to_checkout, and search_shop_policies_and_faqs. WebMCP thus covers a local, observable experience tied to the storefront’s current state.

Why is Shopify moving MCP cart tools toward UCP?

On June 24, 2026, Shopify announced the deprecation of the older Storefront MCP cart tools in favor of UCP-conforming Cart MCP. For those operations, the old /api/mcp endpoint moves to /api/ucp/mcp. Shopify announced that it would maintain the older tools until August 31, 2026. That date applies to cart operations. It does not replace Catalog MCP, Shopify Catalog, or checkout.

Migration involves more than an endpoint change. update_cart uses PUT semantics, so each request replaces the complete cart state. Shopify also requires a meta object carrying the agent profile and a UUID idempotency key for cancel_cart. These constraints align tool invocation with UCP’s Cart model.

For state handling and conversion to payment, see the UCP protocol reference.

Which surface should an implementation choose?

The choice depends on where the agent runs and how broad its search must be. A multi-merchant comparison engine uses Global Catalog. A remote, store-specific agent uses Storefront Catalog and UCP capabilities. An assistant helping a shopper in their tab uses WebMCP to preserve the session and make actions visible.

Three checks prevent architecture errors:

  • identify whether the agent is remote or present in the browser;
  • separate global search, store catalog, and transactional state;
  • retain the same variant identifiers across discovery, cart, and checkout.

UCP remains the shared commercial contract. Catalog MCP is a remote interface that implements that contract. Cart MCP holds cart state. WebMCP is a complementary browser surface. Combining them is coherent when each layer keeps its role and state.

Sources

Back to the UCP and MCP comparison · All notes · Lire en français