The UCP and MCP Endpoints in Your agents.md, Explained

Most coverage of agents.md treats it as a description: a brand brief an agent reads. That's half of it. The other half is the part that makes agents.md different from a plain llms.txt index: it carries the rails an agent transacts on. This post is about those rails, what the UCP and MCP endpoints are, and the flow an agent runs across them.

Two protocols, two jobs

You'll see two endpoints referenced in a well-formed Shopify agents.md:

• UCP discovery at /.well-known/ucp. UCP, the Universal Commerce Protocol, is the commerce standard. The discovery endpoint is the agent's first call: it returns what your store supports, which protocol versions, which capabilities, which payment handlers. It's the "what can this store do" answer.
• MCP endpoint at /api/ucp/mcp. MCP, the Model Context Protocol, is the transport an agent uses to call tools. This is where the agent actually does things: searches your catalog, builds a cart, creates a checkout. It's the "now do it" channel.

The clean way to think about it: UCP is the menu, MCP is the kitchen. The agent reads the menu to see what's possible, then sends orders to the kitchen. agents.md is the sign on the door that points at both.

Why both live in agents.md

agents.md is where an agent starts, so it's where the rails belong. An agent that has your store in view fetches agents.md, learns what you are, and finds the two endpoints it needs to transact. Without them, the file is a brochure: the agent understands your brand but has no supported way to buy, so it falls back to scraping your storefront, parsing HTML, guessing at price and availability, and getting it wrong often enough to not recommend you.

This is the difference between agents.md and the older llms.txt index. llms.txt says "here are my pages." agents.md says "here's how you do business with me." The endpoints are what make it a storefront for agents, not just a sitemap.

The discovery-to-checkout flow

Here's the sequence a shopping agent runs, and what each step uses:

1. Discover: GET /.well-known/ucp. Confirm the store's capabilities and supported versions before doing anything else.
2. Search: call search_catalog over the MCP endpoint to find products matching the shopper's intent.
3. Cart: create_cart to add the chosen items.
4. Checkout: create_checkout, then update_checkout to set the shipping address and method.
5. Complete: complete_checkout to finalize. Critically, this requires the buyer's explicit, contemporaneous approval before payment. An agent should never complete payment on its own.

A good agents.md spells out this flow and the rules around it (human approval for checkout, backing off on rate limits, passing buyer context like country and currency for accurate pricing). That's not decoration: it tells the agent how to transact the supported way, which is faster and more reliable than improvising.

You don't build the endpoints. You point at them correctly.

On Shopify, these endpoints are provided by the platform at standard paths on your domain. You don't implement UCP or MCP yourself. What you do in agents.md is reference them correctly, and the right way is to use Shopify's agents Liquid object rather than hardcoding URLs:

Why the objects and not the raw URLs? Freshness. The endpoints are how an agent actually transacts, and they're Shopify's to change. Reference the objects and your file follows the platform; hardcode them and the day Shopify moves an endpoint, your file hands agents a dead address. (More on the agents object in the pillar.)

Getting it right without hand-writing it

The endpoints, the flow, and the rules need to be precise, an agent acts on them literally. AgentReady generates an agents.md with the UCP and MCP rails matched to Shopify's, alongside your brand content, so you don't have to keep the transaction section correct by hand. For where these rails sit among the other discovery files, see robots.txt vs llms.txt vs agents.md; for the broader picture, the complete agentic commerce guide.

The free AI-readiness checker reads your store the way an agent does and reports whether your agents.md is set up to be understood and transacted with.

Run the checker to see what an agent can do with your store today.