# Shopify UCP tool boundary — shopper agent

Mark **Allow** or **Deny** before you register a Gateway target. The adapter you own injects `meta.ucp-agent.profile`. AgentCore Gateway can target an MCP URL; it does not negotiate UCP for you.

Endpoint for catalog, cart, and checkout tools: `https://{shop}/api/ucp/mcp`

Cart and checkout capability version to declare on the profile: `2026-08-25` (`dev.ucp.shopping.cart`, `dev.ucp.shopping.checkout`).

| Tool | Surface | Auth | Shopper week one | Idempotency / check |
| --- | --- | --- | --- | --- |
| `search_catalog` | Storefront Catalog MCP | Profile required; anonymous allowed | Allow | Read the returned price in minor units. Do not invent a dollar amount. |
| `lookup_catalog` | Storefront Catalog MCP | Same as search | Allow | Use for ids you already hold. Not a second search loop. |
| `get_product` | Storefront Catalog MCP | Same as search | Allow | Confirm the size L variant exists and is available before you recommend it. |
| `create_cart` | Cart MCP | Unauthenticated, profile required | Allow | Store the returned cart id in the session. Read the cart back. |
| `get_cart` | Cart MCP | Same as create | Allow | This is the success check. The model does not declare the add. |
| `update_cart` | Cart MCP | Same as create | Allow | Replaces the **full** cart. Send every line you intend to keep. |
| `cancel_cart` | Cart MCP | Same as create | Deny by default | Docs require `meta.idempotency-key`. A person or an explicit cancel intent. |
| `create_checkout` | Checkout MCP | Authenticated or signed. Anonymous is not enough. | Deny until the buyer is ready | Pass `cart_id`. Profile must declare cart and checkout. |
| `get_checkout` | Checkout MCP | Same as create | Deny until a checkout exists | Read state. Do not describe a checkout you have not fetched. |
| `update_checkout` | Checkout MCP | Same as create | Deny | Buyer edits belong on the merchant checkout when you are unsure. |
| `complete_checkout` | Checkout MCP | Token tier, and only if that token may complete purchases. Signed and anonymous: no. | Deny | May return `requires_escalation` and `continue_url`. Hand the buyer the URL. |
| `cancel_checkout` | Checkout MCP | Same as create | Deny | Retry only with an idempotency key. |
| `get_order` | Order MCP | Token tier, `read_global_api_orders`. 60-minute token. Orders this agent placed only. | Deny on the shopper shopping turn | Buyer-initiated "where is my order" is a separate allow, after checkout exists. |
| `getOrder` / `getProduct` | Admin GraphQL, version pinned in the app | Admin app token, read scopes | Deny | Different secret. See the Admin scopes post. |
| `refund` / `cancel_order` / `update_inventory` / `apply_discount` | Admin mutations | Write scopes | Deny | Not tools. A person signs money and stock. |

## Credential split

| Secret | Who | Where it lives |
| --- | --- | --- |
| UCP agent profile URL | Public document | `https://{your-agent}/.well-known/ucp` |
| Signing key or Global API JWT for checkout / orders | Adapter outbound | AgentCore Identity or Secrets Manager. Not the prompt. |
| Admin offline or online access token | Merchant tools only | A second secret. Never the shopper session. |

## What the adapter must do on every UCP call

- Add `meta.ucp-agent.profile`.
- On `cancel_cart`, and on checkout retries, add an idempotency key for the business action. The key is not the model attempt number.
- On HTTP 429, honor `Retry-After` and back off with jitter. Tell the model the shop is busy. Do not call a different tool instead.
- Return the tool result to the model only after the read-back (`get_cart` or `get_checkout`) matches the claim.

## Explicitly not in this worksheet

Global Catalog MCP, ACP partner checkout, theme code, and a measured conversion rate.