REST API transport
UCP Playground uses REST as the main transport for REST-only stores, and as a fallback when an MCP call fails. The UCP specification defines the REST endpoints agents use to search, build a cart and check out.
REST-only stores
Stores that declare only a rest transport in their UCP profile (/.well-known/ucp) work in the Playground as they are. With no MCP endpoint, the Playground maps each tool call the agent makes to your REST endpoints. A run on a store that declares both uses MCP first.
REST has no tool list to ask for, so the tools come from the capabilities your profile declares, under the names the MCP binding uses. A store that declares dev.ucp.shopping.catalog.lookup gets both of its operations: lookup_catalog (several ids in one call) and get_product (one product in full). Inspect works the same way: at a REST-only store it starts over REST and lists the same tools.
{
"ucp": {
"version": "2026-08-25",
"services": {
"dev.ucp.shopping": [{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/overview",
"transport": "rest",
"schema": "https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json",
"endpoint": "https://yourstore.com/wp-json/wc/ucp/v1"
}]
}
}
}REST endpoint paths
The Playground calls these paths, relative to your declared endpoint. For a store on UCP 2026-08-25:
POST /catalog/search— search products, with the query and filters in the bodyPOST /catalog/lookup— look up several products by ID in one call (ids)POST /catalog/product— read one product in full (id)POST /carts,GET /carts/:id,PUT /carts/:id,POST /carts/:id/cancel— create, read, replace and cancel a cartPOST /checkout-sessions— create a checkoutGET /checkout-sessions/:id— read a checkoutPUT /checkout-sessions/:id— update a checkout. The body is the whole checkout, not just the fields that changed.POST /checkout-sessions/:id/complete— complete a checkoutPOST /checkout-sessions/:id/cancel— cancel a checkoutGET /orders/:id— read an orderPOST /common/locations/search,POST /common/locations/lookup— find locations, if you declare them
For stores on earlier releases, the Playground updates a checkout with a partial PATCH /checkout-sessions/:id and uses a single /cart path (POST /cart, GET /cart/:id, PATCH /cart/:id).
// POST /catalog/search
{
"query": "running shoes",
"limit": 10
}
// Response
{
"ucp": { "version": "2026-08-25" },
"products": [
{
"id": "123",
"title": "Trail Runner",
"price_range": { "min": { "amount": 14500, "currency": "USD" } }
}
],
"pagination": { "has_next_page": false, "total_count": 1 }
}Permalinks are not a REST call
A UCP shopping permalink (dev.ucp.shopping.permalink) is a browser link your store answers with 303 See Other, not an operation of the REST binding. When your profile declares the capability, runs and Inspect get an open_permalink tool that writes the link, opens it once without following the redirect, and checks your answer against the capability's rules. See Inspect.
Legacy fallback
For stores on older REST conventions, the Playground also tries legacy paths:
GET /products?search=query— legacy search with query parametersGET /products/:id— legacy product lookup by ID
It tries the UCP paths first, then the legacy ones.
MCP-to-REST fallback
When a store has both MCP and REST endpoints, the Playground uses MCP first. If an MCP call fails, it checks whether the failure qualifies for a REST fallback:
- Error code
-32601— method not found. The MCP endpoint does not recognise the tool name. - HTTP 4xx or 5xx from MCP — the MCP endpoint is unreachable or misconfigured.
Error code -32603 (internal error) does not trigger a fallback. It means MCP is working but the tool itself failed.
Each tool falls back on its own
The fallback is decided per tool. If search fails over MCP and falls back to REST, checkout still tries MCP first. Once a tool has fallen back to REST in a run, later calls to that tool skip MCP.
Something wrong on this page?