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

You can also sign your requests with HTTP Message Signatures, either Web Bot Auth or UCP request signatures. The store checks the signature against the keys you publish and records whether it verified. Unsigned requests are still answered.

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 . Pickup: pickup from the store's shops, found with search_locations.

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