What is /.well-known/ucp?

It is the Universal Commerce Protocol business profile: a JSON document listing the UCP version, the services (MCP, REST, A2A or embedded endpoints) and the shopping capabilities a store supports. AI agents fetch it to learn how to search, build a cart and check out.

Does Medusa support UCP?

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

Which UCP capabilities do I need to pass the check?

All four core shopping capabilities: catalog (search or lookup), cart, checkout and order. A valid profile with fewer of them earns partial credit.

Is UCP the same as OpenAI ACP?

No. UCP is an open standard published at ucp.dev and has a public discovery file. OpenAI and Stripe's Agentic Commerce Protocol (ACP) uses feeds pushed to OpenAI and has no public file, so it cannot be detected from a store URL.

UCP profile at /.well-known/ucp: make your store agent-ready

Why does a UCP profile matter for AI agents?

The Universal Commerce Protocol (UCP) is an open standard that lets AI shopping agents discover what a store can do and then run catalog search, cart, checkout and order lookup over MCP, REST, A2A or an embedded transport. It launched in January 2026 under Apache-2.0 and is published at ucp.dev.

UCP is the only agentic commerce protocol with a public, crawlable discovery file. An agent that knows nothing about your store can request /.well-known/ucp and learn which endpoint to call and which shopping actions are supported. Without the profile, the agent falls back to parsing HTML, which is slower and breaks easily. That is why this is a high-weight check in the agentic commerce category.

What does the scanner check?

The scanner requests GET /.well-known/ucp with Accept: application/json and parses the response.

Valid profile: the JSON (wrapped in a top-level ucp object, or flat) has a version in YYYY-MM-DD form and at least one entry in services.
Capabilities: the scanner looks for four core shopping capabilities:
- catalog: any dev.ucp.shopping.catalog* capability, such as .catalog.search or .catalog.lookup
- dev.ucp.shopping.cart
- dev.ucp.shopping.checkout
- dev.ucp.shopping.order

Result	When
Pass	Valid profile that declares all four core capabilities.
Partial	Valid profile missing one or more core capabilities. Credit scales with how many are present (25% base + 75% × share of the four).
Fail	`/.well-known/ucp` is missing, not JSON, or has no valid `version` or `services`.

The scanner also reports the number of service bindings, their transports and the number of payment handlers. Whether the declared endpoint actually answers is scored separately in the live agent endpoint check. Advertising the profile with rel="ucp" is a bonus signal.

How do I publish a UCP profile?

Serve a JSON document at /.well-known/ucp with Content-Type: application/json. The minimal shape below includes the fields the scanner reads. Check the UCP overview for the full field list, including per-entry versions, supported_versions and optional signing keys.

{
  "ucp": {
    "version": "2026-08-25",
    "services": {
      "dev.ucp.shopping": [{ "transport": "mcp", "endpoint": "https://store.example/api/ucp/mcp" }]
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [{ "version": "2026-08-25" }],
      "dev.ucp.shopping.catalog.lookup": [{ "version": "2026-08-25" }],
      "dev.ucp.shopping.cart": [{ "version": "2026-08-25" }],
      "dev.ucp.shopping.checkout": [{ "version": "2026-08-25" }],
      "dev.ucp.shopping.order": [{ "version": "2026-08-25" }]
    },
    "payment_handlers": {}
  }
}

Then:

Implement the capabilities you declare. Each capability must be backed by working catalog, cart, checkout and order operations at the service endpoint. Don’t list a capability the endpoint can’t serve.
Hand off cleanly when an agent can’t finish. When checkout returns requires_escalation, the UCP checkout spec requires the agent to send the buyer to your continue_url, so make sure that URL opens a working checkout.
Advertise the profile on every page:

Link: </.well-known/ucp>; rel="ucp"

<link rel="ucp" href="/.well-known/ucp" />

Verify with curl -s https://store.example/.well-known/ucp | jq .ucp.capabilities.

How to fix it on Medusa

Medusa has no built-in UCP support and no official UCP guide. To add it:

Serve the profile as a static JSON file at /.well-known/ucp from your storefront or backend.
Back each declared capability with custom API routes that call the Store API for products, carts and orders.
Or evaluate the third-party UCP and ACP plugin listed in the Medusa integrations directory. Medusa doesn’t build or maintain it.

The Medusa agent-readiness guide covers the other protocols Medusa supports, including the official ACP tutorial.

UCP profile at /.well-known/ucp: make your store agent-ready

Why does a UCP profile matter for AI agents?

What does the scanner check?

How do I publish a UCP profile?

How to fix it on Medusa

Sources

Frequently asked questions

Run your store on a platform built for agentic commerce

Deploy on Medusa Cloud

Storefront skills for coding agents