Quickstart: shop a sandbox store with your agent

1. Read the store's profile

Every store publishes its UCP profile at /.well-known/ucp: the spec version it speaks, its transports and the capabilities it declares.

curl https://flowers.ucpsandbox.com/.well-known/ucp

Northlight Flowers declares catalog search, catalog lookup, cart, checkout, order, discount, fulfillment, buyer consent, location search, location lookup, on spec release 2026-08-25, over REST and MCP.

2. Say who your agent is

Every UCP operation needs your platform's profile URL. Over REST it goes in the UCP-Agent header; over MCP, in meta.ucp-agent.profile. Without it the store answers 400 invalid_profile_url. Send an idempotency key on writes so a retry never makes a second checkout: the Idempotency-Key header over REST, meta.idempotency-key over MCP.

UCP-Agent: profile="https://agent.example.com/.well-known/ucp"
Idempotency-Key: 3f6c1c52-7d0e-4b43-9a55-2b1f0c9e8d11

3. Search and build a checkout

Pick the way your agent talks to stores. All three reach the same catalogue, cart and checkout, so a browser and an agent never disagree.

POST https://flowers.ucpsandbox.com/mcp

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "search_catalog", "arguments": {
    "meta": { "ucp-agent": { "profile": "https://agent.example.com/.well-known/ucp" } },
    "catalog": { "query": "birthday bouquet" }
  } } }

// then create_checkout with
//   "meta": { "ucp-agent": { ... }, "idempotency-key": "3f6c1c52-7d0e-4b43-9a55-2b1f0c9e8d11" },
//   "checkout": { "line_items": [ { "item": { "id": "bouquet_ranunculus" }, "quantity": 1 } ] }

curl -X POST https://flowers.ucpsandbox.com/ucp/catalog/search \
  -H 'UCP-Agent: profile="https://agent.example.com/.well-known/ucp"' \
  -H 'Content-Type: application/json' \
  -d '{ "query": "birthday bouquet" }'

curl -X POST https://flowers.ucpsandbox.com/ucp/checkout-sessions \
  -H 'UCP-Agent: profile="https://agent.example.com/.well-known/ucp"' \
  -H 'Idempotency-Key: 3f6c1c52-7d0e-4b43-9a55-2b1f0c9e8d11' \
  -H 'Content-Type: application/json' \
  -d '{ "line_items": [ { "item": { "id": "bouquet_ranunculus" }, "quantity": 1 } ] }'

// Open any store page in a browser with WebMCP (Chrome origin trial):
//   https://flowers.ucpsandbox.com/
// The page registers these tools with navigator.modelContext:
//   search_catalog, lookup_catalog, create_checkout, get_checkout, update_checkout, complete_checkout, get_order, search_locations, lookup_locations
// For test harnesses it also exposes document.modelContext with
// getTools() and executeTool(tool, args).

// e.g. call search_catalog with { "query": "birthday bouquet" }

Start with initialize and tools/list. The server is stateless: no session to keep between calls.

The full contract is at /ucp/openapi.json. A checkout comes back with its status, totals, what is still missing, and a continue_url for the buyer.

WebMCP tools act on the same cart and checkout as UCP. WebMCP is a separate standard, not a UCP transport; we offer both so you can compare them.

4. Pay with a test instrument

Complete the checkout with one of the store's saved test instruments. Use the declining one to see how your agent handles a refusal.

Discount codes: 10OFF (10%), WELCOME20 (20%), FIXED500 ($5.00 off) . Delivery: std-ship, exp-ship-us, exp-ship-intl .

MCP tools on Northlight Flowers

A store lists only the tools for the capabilities it declares. Each tool takes meta with your profile, and returns the UCP object for that capability.

Store versions

A reference store gets a new version number whenever its catalogue or settings change. Copies and experiment stores follow their reference store, so quote the version when you publish a result. The console shows the version an experiment started on and warns if it changed part-way.

Next