Live agent endpoint: MCP or REST shopping API for AI agents

Why does a live agent endpoint matter for AI agents?

A UCP profile tells AI shopping agents where your commerce API lives. The agent endpoint is that API: usually an MCP server (Model Context Protocol, the standard way AI models call external tools) or a REST API that implements UCP catalog, cart, checkout and order operations (UCP overview).

When a profile points to an endpoint that is down, returns 404 or doesn’t speak the declared protocol, agents fail mid-task. An agent that can find your store but can’t call it is no better off than one that can’t find the profile. This check confirms that the endpoint you advertise actually answers, which is why it carries high weight in the agentic commerce category.

What does the scanner check?

The scanner reads services from /.well-known/ucp. It prefers a service with transport: "mcp" and an endpoint, and otherwise uses the first service that has an endpoint.

MCP endpoints get a JSON-RPC tools/list call:

POST /api/ucp/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Both plain JSON and Server-Sent Events (text/event-stream) responses are parsed.

Result	When
Pass	2xx response with a non-empty result.tools array. The tool names are listed in the findings.
Partial	401 with WWW-Authenticate containing resource_metadata (live, but OAuth is required before tools can be listed), or a JSON-RPC error response.
Fail	No response, or an HTTP status without a JSON-RPC body. Also fails when the profile declares no service with an endpoint.
Skipped	No valid UCP profile. The missing profile is penalized once, under the UCP profile check.

REST and other transports get a GET with Accept: application/json. Any response below 500 that isn’t 404 passes. The scanner only confirms the endpoint is reachable; it doesn’t exercise the REST API.

How do I expose a live agent endpoint?

1. Run an MCP server over Streamable HTTP, or a REST API, that implements the UCP shopping services: catalog search and lookup, cart, checkout and order.
2. Declare it in /.well-known/ucp with an absolute URL:

{
  "ucp": {
    "version": "2026-08-25",
    "services": {
      "dev.ucp.shopping": [{ "transport": "mcp", "endpoint": "https://store.example/api/ucp/mcp" }]
    }
  }
}

3. Answer tools/list without auth, or return a discoverable auth challenge. If tools require sign-in, respond to unauthenticated calls with:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://store.example/.well-known/oauth-protected-resource"

The MCP authorization flow uses RFC 9728 protected resource metadata. See the OAuth discovery check.

4. Verify from outside your network:

curl -s -X POST https://store.example/api/ucp/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Also confirm that your bot protection doesn’t block the endpoint. A WAF challenge on the MCP route fails this check just as it fails a real agent. See agent access.

How to fix it on Medusa

• Medusa doesn’t provide a shopper-facing MCP server or UCP endpoint out of the box. Build one with custom API routes that wrap the Store API’s product, cart and order routes, then declare it in your UCP profile.
• The official Medusa MCP server is merchant-facing: read-only, in beta and available on Medusa Cloud for querying store data. Don’t declare it as your shopping endpoint.

See the Medusa agent-readiness guide for the full picture.

Sources

• UCP specification overview
• MCP specification release 2026-07-28
• RFC 9728: OAuth 2.0 Protected Resource Metadata
• Medusa: API routes
• Medusa MCP