Agent-facing endpoints
Once the extension is enabled, your store exposes the following URLs to AI agents. Each is gated by its corresponding switch on the Settings page; when the master switch or the relevant surface is No, the URL returns 404.
All URLs are relative to your store's base URL (for example, https://example.com/agent/mcp).
Discovery
| Endpoint | Description | Controlled by |
|---|---|---|
/.well-known/ucp | UCP merchant profile — declares supported protocol versions, capabilities, the agent endpoints, and the store signing key. The primary discovery document for UCP agents. | Enable UCP Merchant Profile |
/llms.txt | Agent instructions — a Liquid-templated guide telling agents how to work with your store. | Enable Agent Instructions |
/agents.md | A byte-identical mirror of /llms.txt. | Enable Agent Instructions |
/sitemap_agentic_discovery.xml | Agent-discovery sitemap, referenced from /sitemap.xml. | Enable Agentic Discovery Sitemap |
robots.txt (agent block) | An agent block added to the standard robots.txt, pointing agents to /.well-known/ucp and /agents.md. | Enable Agent Block in robots.txt |
Operations
| Endpoint | Description | Controlled by |
|---|---|---|
/agent/mcp | Storefront MCP server (JSON-RPC over HTTP, POST). Exposes the catalogue and cart tools: search_catalog, get_product, lookup_catalog, create_cart, update_cart, get_cart, cancel_cart. On a cart, agents can also price and select delivery and submit coupon codes - see Delivery and discounts on agent carts. | Enable Generic MCP Endpoint |
/agent/products.json | Product listing (browse). Accepts optional ?q= to filter by search term and ?page= for pagination. | Enable Public JSON Read API |
/agent/products/{url_key}.json | A single product by its URL key. | Enable Public JSON Read API |
/agent/collections/{url_key}/products.json | Products in a category, by the category URL key. | Enable Public JSON Read API |
/agent/search.json | Search the catalogue with ?query=. Returns the same results as the search_catalog MCP tool. | Enable Public JSON Read API |
/agent/cart/{maskedId} | The cart continue URL target. When a shopper follows the link an agent provided, this restores the agent-built cart into their browser session and sends them to the cart or checkout (per the Continue URL Landing Page setting). | Enable Agent Cart |
The JSON read endpoints are anonymous and cached (Cache-Control: public). The MCP endpoint and the cart continue URL are not cached. None of these endpoints expose checkout or payment — the shopper always completes the purchase through your normal storefront checkout.
Prices and currency
The extension does not convert prices between currencies. All prices returned by the MCP tools and the JSON read endpoints are in the store's currency, and the JSON responses show its code in context.currency.
The MCP tools accept an optional currency in the buyer context (catalog.context for search_catalog, get_product, and lookup_catalog; cart.context for the cart tools). An agent may leave it out or pass the store's currency. If it passes a different currency, the tool call fails with an error like this:
Currency EUR is not supported; store operates in USD.
This prevents prices in one currency from being shown with the code of another. If an agent needs prices in a different currency, it should request them in the store's currency and convert them on its side.
All agent endpoints (discovery, MCP, and the JSON API) share a per-client rate limit. A client that exceeds it receives a non-cacheable 429 Too Many Requests until the window resets, which protects the store from crawler floods.