REST API Transport

UCP Playground supports REST as both a primary transport (for REST-only stores) and as an automatic fallback when MCP calls fail. The UCP specification defines standard REST endpoints that agents use to search, browse, and check out.

REST-Only Stores

Stores that declare only a rest transport in their /.well-known/ucp manifest work natively in the Playground. When no MCP endpoint is available, the Playground maps each tool call the agent makes to your REST endpoints. On the Agent page you can also pick UCP · REST in the endpoint card's Connection picker to run a store that offers both over REST.

{
  "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 Patterns

The Playground calls these REST paths, relative to your declared endpoint:

• POST /catalog/search — Search products with query and filters in the request body
• POST /catalog/lookup — Look up a single product by ID
• POST /checkout-sessions — Create a new checkout session
• PATCH /checkout-sessions/:id — Update an existing checkout (add buyer info, payment)
• GET /checkout-sessions/:id — Read a checkout
• POST /checkout-sessions/:id/complete — Complete a checkout
• POST /checkout-sessions/:id/cancel — Cancel a checkout
• POST /cart, GET /cart/:id, PATCH /cart/:id — Create, read and update a cart
• GET /orders/:id — Read an order

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

Legacy Fallback

For stores using older REST conventions, the Playground also supports legacy endpoints as a fallback:

• GET /products?search=query — Legacy search with query parameters
• GET /products/:id — Legacy product lookup by ID

The Playground tries the UCP endpoints first, then falls back to legacy paths automatically.

MCP-to-REST Fallback

When a store has both MCP and REST endpoints, the Playground uses MCP as the primary transport. 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 recognize 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 encountered an error.

Per-Tool Independence

Fallback decisions are made independently for each tool. If search fails via MCP and falls back to REST, checkout will still attempt MCP first. Once a tool has fallen back to REST within a session, subsequent requests skip the MCP attempt for that tool to avoid repeated failures.