Discovery & catalog

The storefront's MCP server lives at https://{storefront-domain}/api/mcp (Streamable HTTP, POST only). Connect with a standard MCP client: send initialize, keep the MCP-Session-Id response header for subsequent calls, and use Accept: application/json, text/event-stream.

Two catalog tools are always available wherever the profile resolves: search_catalog and lookup_catalog.

Request metadata

Every UCP tool call should carry a meta argument identifying your agent:

{
  "meta": { "ucp-agent": { "profile": "https://your-platform.example/agent-profile.json" } }
}

Calls without it still succeed but get a warning message in the result. complete_checkout and cancel_checkout additionally requiremeta["idempotency-key"] (see Checkout & booking).

search_catalog

Arguments (inside a catalog object):

Field	Type	Notes
check_in, check_out	Y-m-d	Optional pair; check_out must be after check_in. Omit both to browse.
adults	int ≥ 1	Default 2.
children	int ≥ 0	Default 0.
units	int ≥ 1	Number of units of the same type. Default 1.
query	string	Optional text match on unit-type or property name.

With dates, results are bookable stays only — availability, stay restrictions (min/max stay, closed arrival/departure), and party size are all enforced before an item is returned:

{
  "ucp": { "version": "2026-04-08" },
  "products": [
    {
      "id": "stay:42:2026-08-03:2026-08-10:2:0",
      "title": "Seaside Villa — Deluxe Suite",
      "price": 70000,
      "currency": "EUR",
      "description": "…",
      "available_units": 2,
      "check_in": "2026-08-03",
      "check_out": "2026-08-10",
      "nights": 7,
      "max_guests": 4,
      "url": "https://stay.example.com/accommodations/deluxe-suite"
    }
  ]
}

price is the stay subtotal for the requested party and unit count, in minor units. Taxes and fees are itemized later, on the checkout session.

Without dates, items are unit types ("id": "unit_type:42") with a per-night price and "price_unit": "per_night", and no availability claims.

Stay item ids

Until UCP publishes its lodging extension, the generic schemas carry no check-in/check-out fields — so the item id encodes the whole stay:

stay:{unit_type_id}:{check_in}:{check_out}:{adults}:{children}

Treat it as opaque: take ids from search_catalog results and pass them to create_checkout unchanged. quantity on the checkout line item is the number of units; all line items in one checkout must share the same dates.

lookup_catalog

One argument: id — either form above. Returns the same item shape (products with a single entry) with live pricing, plus an available boolean for stay ids. Unknown ids return a tool error.