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. | 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.
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.