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

> A live agent endpoint is the MCP or REST API declared in your UCP profile that AI agents call to search products, manage carts and check out. Declaring the endpoint is not enough: it has to answer. For MCP, that means responding to a tools/list request.

- Source: https://is-agentic-storefront.com/checks/agent-endpoint
- Updated: 2026-10-15
- Category: Agentic commerce (15% of score)
- Impact: High
- Spec: [UCP specification](https://ucp.dev/latest/specification/overview/)
- Scanner check: Live agent endpoint (MCP/REST) from the UCP profile

## Why does a live agent endpoint matter for AI agents?

A [UCP profile](https://is-agentic-storefront.com/checks/ucp-profile) tells AI shopping agents where your commerce API lives. The **agent endpoint** is that API: usually an [MCP](https://modelcontextprotocol.io/) 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](https://ucp.dev/2026-08-25/specification/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:

```http
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](https://is-agentic-storefront.com/checks/ucp-profile).                                     |

**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:

```json
{
  "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
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](https://datatracker.ietf.org/doc/html/rfc9728) protected resource metadata. See the [OAuth discovery check](https://is-agentic-storefront.com/checks/oauth-discovery).

4. **Verify** from outside your network:

```bash
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](https://is-agentic-storefront.com/checks/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](https://docs.medusajs.com/learn/fundamentals/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](https://docs.medusajs.com/cloud/medusa-mcp) 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](https://is-agentic-storefront.com/guides/medusa-agent-readiness) for the full picture.

## Sources

- [UCP specification overview](https://ucp.dev/2026-08-25/specification/overview/)
- [MCP specification release 2026-07-28](https://blog.modelcontextprotocol.io/posts/2026-07-28/)
- [RFC 9728: OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)
- [Medusa: API routes](https://docs.medusajs.com/learn/fundamentals/api-routes)
- [Medusa MCP](https://docs.medusajs.com/cloud/medusa-mcp)

## Frequently asked questions

### How do I test if my store's MCP server is working?

POST {"jsonrpc":"2.0","id":1,"method":"tools/list"} to the MCP endpoint URL from your /.well-known/ucp profile. A working server returns a JSON-RPC result with a non-empty tools array.

### Can my MCP endpoint require OAuth?

Yes. If it returns 401 with a WWW-Authenticate: Bearer resource_metadata="..." header, agents can discover how to authenticate. The scanner gives that partial credit because tools can't be listed anonymously.

### Why is this check skipped for my store?

The scanner reads the endpoint from your UCP profile. If there is no valid profile, there is nothing to probe, and the missing profile is already scored under the UCP profile check.

## 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=%2Fchecks%2Fagent-endpoint)
- [Medusa Cloud docs](https://docs.medusajs.com/cloud?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Fagent-endpoint)

### 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/