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

> With Medusa, you own the storefront, so every agent-readiness fix is a change in your own code, not a theme or app workaround. The Next.js Starter server-renders product pages; Product JSON-LD, a sitemap, robots.txt, llms.txt and a form-based add-to-cart are short additions. Medusa has an official tutorial for OpenAI's Agentic Commerce Protocol. UCP and a shopper-facing MCP server can be built but are not included.

- Source: https://is-agentic-storefront.com/guides/medusa-agent-readiness
- Updated: 2026-10-15

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](https://docs.medusajs.com/resources/nextjs-starter), which `create-medusa-app` installs in a monorepo with the backend (source: [dtc-starter](https://github.com/medusajs/dtc-starter)). It maps each check in the [agent-ready ecommerce](https://is-agentic-storefront.com/guides/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](https://docs.medusajs.com/resources/storefront-development/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](https://is-agentic-storefront.com/checks/agent-access) | Depends on your host and CDN                 | Allow [AI user agents](https://is-agentic-storefront.com/guides/ai-user-agents) at the edge.     |
| [robots.txt](https://is-agentic-storefront.com/checks/robots-txt)              | Not shipped                                  | Add `app/robots.ts`.                                            |
| [No CAPTCHA](https://is-agentic-storefront.com/checks/no-captcha)              | None by default                              | Keep it that way on product pages and the cart.                 |
| [No content gates](https://is-agentic-storefront.com/checks/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](https://is-agentic-storefront.com/checks/ssr-product-facts)       | Name and price render on the server | Add structured data so currency and availability are explicit. |
| [Product JSON-LD](https://is-agentic-storefront.com/checks/product-json-ld)               | None                                | Add it in the product page server component.                   |
| [Variants modeled](https://is-agentic-storefront.com/checks/product-variants)             | None                                | Output `ProductGroup` with `hasVariant`.                       |
| [Return and shipping data](https://is-agentic-storefront.com/checks/return-shipping-data) | None                                | Add `MerchantReturnPolicy` and `OfferShippingDetails`.         |
| [OpenGraph price tags](https://is-agentic-storefront.com/checks/opengraph-product)        | `og:title` and `og:image` only      | Add `og:price:*` in `generateMetadata`.                        |

### Discovery

| Check                                                  | Default on the Medusa starter                            | What to do                                 |
| ------------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------ |
| [Sitemap](https://is-agentic-storefront.com/checks/sitemap)                             | Not shipped                                              | Add `app/sitemap.ts`.                      |
| [Canonical and status codes](https://is-agentic-storefront.com/checks/canonical-status) | The product route calls `notFound()` for unknown handles | Add a canonical URL in `generateMetadata`. |
| [Performance](https://is-agentic-storefront.com/checks/performance)                     | Depends on hosting                                       | Cache product pages.                       |
| [Markdown alternative](https://is-agentic-storefront.com/checks/markdown-alternative)   | Not shipped                                              | Low weight. Optional.                      |
| [llms.txt / agents.md](https://is-agentic-storefront.com/checks/llms-txt)               | Not shipped                                              | Add a route handler.                       |

### Operability

| Check                                            | Default on the Medusa starter                              | What to do                                               |
| ------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------- |
| [Add-to-cart in a form](https://is-agentic-storefront.com/checks/add-to-cart)     | A named `<button>` with `onClick`, no `<form>`             | Wrap it in a form that calls a server action.            |
| [Variant controls](https://is-agentic-storefront.com/checks/variant-controls)     | Plain `<button>`s with no `aria-pressed` or `aria-checked` | Use radio inputs, or add ARIA state.                     |
| [Accessible names](https://is-agentic-storefront.com/checks/accessible-names)     | Depends on your customizations                             | Name any icon-only buttons.                              |
| [Site search](https://is-agentic-storefront.com/checks/site-search)               | Client-side search drawer, no GET results page             | Add a server-rendered `/search?q=` route.                |
| [Policy links](https://is-agentic-storefront.com/checks/policy-links)             | No policy links in the footer                              | Add returns, shipping, terms, privacy and contact pages. |
| [Semantic structure](https://is-agentic-storefront.com/checks/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](https://is-agentic-storefront.com/checks/ucp-profile)                                                                                                                                                                                                                  | Not built in                 | Build it with custom API routes, or evaluate a third-party plugin. |
| [Live agent endpoint](https://is-agentic-storefront.com/checks/agent-endpoint)                                                                                                                                                                                                       | No shopper-facing MCP server | Build one with the UCP profile.                                    |
| [Checkout permalinks](https://is-agentic-storefront.com/checks/checkout-permalinks)                                                                                                                                                                                                  | Not built in                 | Add a storefront route that builds a cart and redirects.           |
| [OAuth discovery](https://is-agentic-storefront.com/checks/oauth-discovery)                                                                                                                                                                                                          | Not built in for storefronts | Needed only with an agent endpoint                                 |
| Bonus checks ([WebMCP](https://is-agentic-storefront.com/checks/bonus-signals#webmcp), [A2A](https://is-agentic-storefront.com/checks/bonus-signals#a2a-agent-card), [AI Catalog](https://is-agentic-storefront.com/checks/bonus-signals#ai-catalog), [API catalog](https://is-agentic-storefront.com/checks/bonus-signals#api-catalog), [`rel="ucp"`](https://is-agentic-storefront.com/checks/bonus-signals#ucp-link)) | 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](https://nextjs.org/docs/app/guides/json-ld) recommends:

```tsx
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](https://developers.google.com/search/docs/appearance/structured-data/product-variants)). Then add `MerchantReturnPolicy` and `OfferShippingDetails`. Google accepts both at Organization level ([return policy](https://developers.google.com/search/docs/appearance/structured-data/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](https://is-agentic-storefront.com/guides/ai-user-agents) 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](https://docs.medusajs.com/resources/storefront-development/products/list#filter-products)) 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](https://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](https://docs.medusajs.com/resources/how-to-tutorials/tutorials/agentic-commerce) 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](https://docs.medusajs.com/learn/fundamentals/api-routes) on top of the Store API ([UCP spec](https://ucp.dev/2026-08-25/specification/overview/)). A [third-party UCP and ACP plugin](https://medusajs.com/integrations/@financedistrictmedusa-plugin-agentic-commerce) is listed in the Medusa integrations directory. Medusa doesn't build or maintain it.
- **MCP**: the [Medusa MCP server](https://docs.medusajs.com/cloud/medusa-mcp) 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](https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/ecommerce-storefront/skills/storefront-best-practices) covers Product JSON-LD and SEO metadata for storefronts.

## Scan your store

[Run the free scan](https://is-agentic-storefront.com/) 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](https://is-agentic-storefront.com/glossary). For protocol background, see the [agentic commerce protocols guide](https://is-agentic-storefront.com/guides/agentic-commerce-protocols).

## Sources

- [Medusa: Next.js Starter Storefront](https://docs.medusajs.com/resources/nextjs-starter)
- [Medusa dtc-starter source](https://github.com/medusajs/dtc-starter)
- [Medusa: publishable API keys](https://docs.medusajs.com/resources/storefront-development/publishable-api-keys)
- [Medusa: list products and filter by keyword](https://docs.medusajs.com/resources/storefront-development/products/list#filter-products)
- [Medusa: Agentic Commerce tutorial](https://docs.medusajs.com/resources/how-to-tutorials/tutorials/agentic-commerce)
- [Medusa: Medusa MCP](https://docs.medusajs.com/cloud/medusa-mcp)
- [Medusa: API routes](https://docs.medusajs.com/learn/fundamentals/api-routes)
- [Medusa integrations: agentic commerce plugin (third party)](https://medusajs.com/integrations/@financedistrictmedusa-plugin-agentic-commerce)
- [Medusa agent skills: storefront-best-practices](https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/ecommerce-storefront/skills/storefront-best-practices)
- [Next.js: JSON-LD guide](https://nextjs.org/docs/app/guides/json-ld)
- [Google: product variants structured data](https://developers.google.com/search/docs/appearance/structured-data/product-variants)
- [Google: return policy structured data](https://developers.google.com/search/docs/appearance/structured-data/return-policy)
- [UCP specification](https://ucp.dev/2026-08-25/specification/overview/)
- [llms.txt proposal](https://llmstxt.org/)
- [OpenAI: Agentic Commerce Protocol](https://developers.openai.com/commerce)

## Frequently asked questions

### Does Medusa support the Universal Commerce Protocol (UCP)?

Not out of the box, and there is no official Medusa guide for it. You can build a UCP profile and endpoints with custom API routes. A third-party plugin is listed in the Medusa integrations directory.

### Does Medusa support OpenAI's Agentic Commerce Protocol (ACP)?

Medusa has an official tutorial that implements an ACP product feed, Agentic Checkout APIs and webhooks. It predates OpenAI moving ChatGPT checkout to merchant sites in March 2026.

### Is the Medusa MCP server for shopping agents?

No. The Medusa MCP server is for merchants. It is read-only, in beta and available for stores on Medusa Cloud. It is not a shopper-facing storefront MCP server.

### Does the Medusa Next.js Starter output Product JSON-LD or a sitemap?

No. The starter sets page titles and OpenGraph metadata, but ships no Product JSON-LD, sitemap.xml, robots.txt or llms.txt. You add them in the storefront.

## Run your store on a platform built for agentic commerce

Medusa is open-source, headless commerce with a full Store API agents can call and storefronts you control end to end.

### Deploy on Medusa Cloud

Open-source commerce with a full Store API, hosted and scaled for you. Your storefront, your data model.

- [Deploy on Medusa Cloud](https://cloud.medusajs.com?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fguides%2Fmedusa-agent-readiness)
- [Medusa Cloud docs](https://docs.medusajs.com/cloud?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fguides%2Fmedusa-agent-readiness)

### Storefront skills for coding agents

Teach Claude Code, Cursor or Codex to build storefronts with the patterns these checks look for.

```bash
npx skills add medusajs/medusa-agent-skills
```

[View the skill on GitHub](https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/ecommerce-storefront/skills/storefront-best-practices)

---

Scan your store for free at https://is-agentic-storefront.com/