---
title: Build directly with UCP
description: >-
  Build directly against Shopify's Universal Commerce Protocol (UCP) servers,
  from product discovery to order tracking.
source_url:
  html: 'https://shopify.dev/docs/agents/ucp'
  md: 'https://shopify.dev/docs/agents/ucp.md'
---

# Build directly with UCP

Call Shopify's [Universal Commerce Protocol (UCP)](https://ucp.dev) servers directly to discover products, build carts, create checkouts, and track orders.

[Start building\
\
](https://shopify.dev/docs/agents/get-started/quickstart)

[Install the UCP CLI, then walk the full flow from discovery to order tracking.](https://shopify.dev/docs/agents/get-started/quickstart)

## Install the UCP CLI

**Note:**

Start with [Shop MCP](https://shopify.dev/docs/agents/shop-mcp) for most agents and apps. For exceptions and other options, refer to [Choose your path](https://shopify.dev/docs/agents#choose-your-path).

Install the UCP CLI and [Shopify AI Toolkit](https://shopify.dev/docs/apps/build/ai-toolkit) plugin for your supported AI tool. Built for agent workflows, the CLI provides structured commands to search the Catalog, build carts, create checkouts, hand off buyers, and track orders. The toolkit's `ucp` skill helps agents apply UCP best practices against each merchant's live schema.

Before you install, make sure you have Node.js 22.19.0 or higher. The toolkit is supported on any agent that supports the skills format.

#### Claude Code

## Terminal: Install the UCP CLI

```terminal
npm install -g @shopify/ucp-cli
```

## Terminal: Install the Shopify plugin

```terminal
claude plugin install shopify-ai-toolkit@claude-plugins-official
```

#### Codex

## Terminal: Install the UCP CLI

```terminal
npm install -g @shopify/ucp-cli
```

## Terminal: Install the Shopify plugin

```terminal
codex plugin add shopify@openai-curated
```

#### Antigravity CLI

## Terminal: Install the UCP CLI

```terminal
npm install -g @shopify/ucp-cli
```

## Terminal: Install the Shopify plugin

```terminal
agy plugin install https://github.com/Shopify/shopify-ai-toolkit
```

#### Cursor

## Terminal: Install the UCP CLI

```terminal
npm install -g @shopify/ucp-cli
```

## Cursor Chat:

```terminal
/add-plugin shopify
```

#### VS Code

## Terminal: Install the UCP CLI

```terminal
npm install -g @shopify/ucp-cli
```

## Command Palette > Chat: Install Plugin From Source

https://github.com/Shopify/shopify-ai-toolkit

***

## Understand how Shopify does UCP

Shopify's MCP tools implement UCP at every step of the buyer journey:

* **Negotiate and authenticate**: Identify your agent so Shopify can set its rate limits and tool access.
* **Discover products**: Search across hundreds of millions of Shopify listings.
* **Carts and checkout**: Build carts, convert them to checkouts, and hand off to the merchant for payment.
* **Monitor orders**: Receive order webhooks and fetch fresh order state on demand.

![The four-stage agentic commerce buyer journey: discovery, cart, checkout, and orders, connected by dashed arrows.](https://shopify.dev/assets/assets/images/agents/ucp-flow-4-light-C9RMxm5d.png)

***

## ![Step 1](https://shopify.dev/assets/assets/images/icons/32/number-1-DG-dFgp6.png) Negotiate and authenticate

Publish a profile, a JSON file that describes your agent, so Shopify can verify who's calling. How your agent identifies itself sets its rate limits and which tools it can use. Shopify calls these levels trust tiers. Agents that authenticate with a token can get permission to complete checkouts themselves, instead of sending buyers to the merchant's checkout page. You host the profile at a well-known URL and reference it on every UCP request. The UCP CLI uses a Shopify-managed profile until you publish your own.

[About profiles\
\
](https://shopify.dev/docs/agents/profiles)

[Host a UCP profile for capability negotiation and signed-request verification.](https://shopify.dev/docs/agents/profiles)

[Auth and rate limiting\
\
](https://shopify.dev/docs/agents/profiles/auth-and-rate-limiting)

[What each trust tier can do, and its rate limits.](https://shopify.dev/docs/agents/profiles/auth-and-rate-limiting)

![Diagram showing an agent presenting its profile to Shopify, with a key icon representing authenticated capability negotiation.](https://shopify.dev/assets/assets/images/agents/agents-auth-light-BQxS1ihn.png)

***

## ![Step 2](https://shopify.dev/assets/assets/images/icons/32/number-2-KzqDfbX_.png) Discover products

Query products across all Shopify merchants with the Global Catalog, or scope results to a single merchant with a Storefront Catalog. When buyers pick a product, fetch the variant details you need to build a cart or hand off to a checkout permalink.

[Global Catalog\
\
](https://shopify.dev/docs/agents/catalog/global-catalog)

[Search products across every Shopify merchant from a single endpoint.](https://shopify.dev/docs/agents/catalog/global-catalog)

[Storefront Catalog\
\
](https://shopify.dev/docs/agents/catalog/storefront-catalog)

[Scope discovery to a single merchant's storefront.](https://shopify.dev/docs/agents/catalog/storefront-catalog)

![Search results across multiple Shopify merchants, with product titles, images, and variant details surfaced for an agent to act on.](https://shopify.dev/assets/assets/images/agents/catalog-light-wSL3czp-.png)

***

## ![Step 3](https://shopify.dev/assets/assets/images/icons/32/number-3-69W0NVcD.png) Build carts and convert to checkout

Build carts as buyers iterate. Add line items, apply localization, and estimate totals across multiple turns of conversation. When buyers are ready, convert the cart into a checkout and refer them to the merchant storefront to complete payment. Agents that Shopify has given permission to complete checkouts can finish the purchase themselves.

[Cart MCP\
\
](https://shopify.dev/docs/agents/carts-and-checkout/cart-mcp)

[Build and iterate on carts with line items, localization, and buyer context.](https://shopify.dev/docs/agents/carts-and-checkout/cart-mcp)

[Checkout MCP\
\
](https://shopify.dev/docs/agents/carts-and-checkout/checkout-mcp)

[Convert carts into checkouts, and complete purchases when your agent has permission.](https://shopify.dev/docs/agents/carts-and-checkout/checkout-mcp)

![A checkout session with line items, fulfillment options, and a continue link that hands the buyer off to the merchant storefront.](https://shopify.dev/assets/assets/images/agents/zoomedcheckoutlight-6vMgJOBz.png)

***

## ![Step 4](https://shopify.dev/assets/assets/images/icons/32/number-4-DqGMO7Cl.png) Monitor orders

After checkout, monitor order lifecycle changes (fulfillment events, refunds, returns, exchanges, and cancellations) with order webhooks in the UCP format. Fetch fresh order state on demand with the `get_order` MCP tool when the buyer asks "Where's my order?" or when reconciling a missed webhook.

[Order MCP\
\
](https://shopify.dev/docs/agents/orders/order-mcp)

[Fetch fresh order state on demand with the `get_order` tool.](https://shopify.dev/docs/agents/orders/order-mcp)

[Order webhooks\
\
](https://shopify.dev/docs/agents/orders/order-webhooks)

[Subscribe to lifecycle events for fulfillment, returns, refunds, and edits.](https://shopify.dev/docs/agents/orders/order-webhooks)

![An order detail view showing fulfillment status, line items, and post-purchase adjustments returned by get\_order and order webhooks.](https://shopify.dev/assets/assets/images/agents/order-light-DsWFrEev.png)

***
