Is Medusa agent-ready? Build an agent-ready storefront you control

Medusa is a headless commerce platform, so you decide exactly what AI agents receive. The backend exposes the Store API, and agents see whatever your storefront renders: no theme limits, app conflicts or platform defaults to work around. This guide covers the Medusa Next.js Starter Storefront, which create-medusa-app installs in a monorepo with the backend (source: dtc-starter). It maps each check in the agent-ready ecommerce score to what the stock starter gives you, then lists what to add. If you built your own storefront, use the tables as a checklist.

What does a Medusa store give AI agents by default?

The starter fetches products from the Store API in server components, so product names and prices are in the HTML that agents fetch. Every /store request needs an x-publishable-api-key header (publishable API keys). The discovery files agents use are yours to add, in a few Next.js route files. We read the starter source in October 2026 and found no Product JSON-LD, sitemap, robots.txt or llms.txt. Its add-to-cart button also sits outside any <form>.

Access

Check	Default on the Medusa starter	What to do
AI agents not blocked	Depends on your host and CDN	Allow AI user agents at the edge.
robots.txt	Not shipped	Add app/robots.ts.
No CAPTCHA	None by default	Keep it that way on product pages and the cart.
No content gates	Middleware redirects / to /{countryCode}	Fine for most agents. Consider serving a default region at /.

Product data

Check	Default on the Medusa starter	What to do
Product facts in HTML	Name and price render on the server	Add structured data so currency and availability are explicit.
Product JSON-LD	None	Add it in the product page server component.
Variants modeled	None	Output ProductGroup with hasVariant.
Return and shipping data	None	Add MerchantReturnPolicy and OfferShippingDetails.
OpenGraph price tags	og:title and og:image only	Add og:price:* in generateMetadata.

Discovery

Check	Default on the Medusa starter	What to do
Sitemap	Not shipped	Add app/sitemap.ts.
Canonical and status codes	The product route calls notFound() for unknown handles	Add a canonical URL in generateMetadata.
Performance	Depends on hosting	Cache product pages.
Markdown alternative	Not shipped	Low weight. Optional.
llms.txt / agents.md	Not shipped	Add a route handler.

Operability

Check	Default on the Medusa starter	What to do
Add-to-cart in a form	A named <button> with onClick, no <form>	Wrap it in a form that calls a server action.
Variant controls	Plain <button>s with no aria-pressed or aria-checked	Use radio inputs, or add ARIA state.
Accessible names	Depends on your customizations	Name any icon-only buttons.
Site search	Client-side search drawer, no GET results page	Add a server-rendered /search?q= route.
Policy links	No policy links in the footer	Add returns, shipping, terms, privacy and contact pages.
Semantic structure	header, nav, main and footer present	Check for one h1 and image alt text.

Agentic commerce

Check	Default on Medusa	What to do
UCP profile	Not built in	Build it with custom API routes, or evaluate a third-party plugin.
Live agent endpoint	No shopper-facing MCP server	Build one with the UCP profile.
Checkout permalinks	Not built in	Add a storefront route that builds a cart and redirects.
OAuth discovery	Not built in for storefronts	Needed only with an agent endpoint
Bonus checks (WebMCP, A2A, AI Catalog, API catalog, rel="ucp")	Not built in	Optional

How do I make a Medusa storefront agent-ready, in priority order?

1. Add Product JSON-LD to the product page

Add the JSON-LD in apps/storefront/src/app/[countryCode]/(main)/products/[handle]/page.tsx. The starter already fetches the product there with *variants.calculated_price and +variants.inventory_quantity. Render a <script> tag as the Next.js JSON-LD guide recommends:

const variant = pricedProduct.variants?.[0]
const inStock =
  !variant?.manage_inventory || variant.allow_backorder || (variant.inventory_quantity ?? 0) > 0

const jsonLd = {
  '@context': 'https://schema.org',
  '@type': 'Product',
  name: pricedProduct.title,
  description: pricedProduct.description,
  image: pricedProduct.images?.map((i) => i.url),
  sku: variant?.sku ?? undefined,
  offers: {
    '@type': 'Offer',
    price: variant?.calculated_price?.calculated_amount,
    priceCurrency: variant?.calculated_price?.currency_code?.toUpperCase(),
    availability: inStock ? 'https://schema.org/InStock' : 'https://schema.org/OutOfStock',
  },
}

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, '\\u003c') }}
/>

For products with options, output a ProductGroup with one hasVariant entry per variant (Google product variants). Then add MerchantReturnPolicy and OfferShippingDetails. Google accepts both at Organization level (return policy), so you can put them once in the root layout.

2. Add robots.txt and a sitemap

Add app/robots.ts and app/sitemap.ts with the Next.js Metadata API. The sitemap should page through the Store API’s list products route and output one /{countryCode}/products/{handle} URL per product. Reference the sitemap in robots.ts. Don’t disallow AI search bots or user-initiated agents. The AI user agents guide lists them.

3. Put add-to-cart in a real form

The starter’s add-to-cart is a <button> with an onClick handler. An agent that can’t run JavaScript can’t use it. Wrap it in <form action={addToCartAction}>, with hidden inputs for the variant ID and quantity, and a submit button. Make the server action call the starter’s existing addToCart data function. Render the option buttons as a radio group, or give them role="radio" and aria-checked.

4. Add a GET search page and policy links

Add a /[countryCode]/search route that reads ?q=. It should call the Store API list products route with the q parameter (filter by keyword) and render the results on the server. Then link returns, shipping, terms, privacy and contact pages in the footer.

5. Add llms.txt

Serve /llms.txt from a route handler at app/llms.txt/route.ts that returns text/markdown (llmstxt.org). List your regions, top categories, the search URL and your policy pages.

6. Choose your agentic commerce protocol

• ACP (OpenAI): Medusa has an official tutorial that builds an ACP product feed, Agentic Checkout APIs and webhooks. ACP doesn’t use a public discovery file, so this scan can’t detect it.
• UCP: Medusa doesn’t include UCP and has no official guide for it. The profile is a JSON file at /.well-known/ucp plus REST or MCP endpoints, which you can build with custom API routes on top of the Store API (UCP spec). A third-party UCP and ACP plugin is listed in the Medusa integrations directory. Medusa doesn’t build or maintain it.
• MCP: the Medusa MCP server lets merchants query their Cloud store’s data from AI tools. Shopping agents can’t use it to browse or buy.

If you use an AI coding agent, Medusa’s storefront-best-practices skill covers Product JSON-LD and SEO metadata for storefronts.

Scan your store

Run the free scan on your storefront URL to see which of these checks you already pass. Every failing check comes with a fix prompt you can copy. Terms are defined in the glossary. For protocol background, see the agentic commerce protocols guide.

Sources

• Medusa: Next.js Starter Storefront
• Medusa dtc-starter source
• Medusa: publishable API keys
• Medusa: list products and filter by keyword
• Medusa: Agentic Commerce tutorial
• Medusa: Medusa MCP
• Medusa: API routes
• Medusa integrations: agentic commerce plugin (third party)
• Medusa agent skills: storefront-best-practices
• Next.js: JSON-LD guide
• Google: product variants structured data
• Google: return policy structured data
• UCP specification
• llms.txt proposal
• OpenAI: Agentic Commerce Protocol