Building UCP Agents

Using the UCP CLI

Shopify's ucp-cli is a shopping skill for AI agents. It gives any agent the ability to search products, build carts, and complete checkouts against any UCP-enabled merchant.

Install

npm install -g @shopify/ucp-cli

# Add the UCP skill to your agent
ucp skills add

Search products

# Global catalog search (all UCP merchants)
ucp catalog search "wireless headphones under $200"

# Per-merchant search
ucp catalog search "coffee" --business https://shop.example.com

# Get input schema for any command
ucp checkout create --input-schema --business https://shop.example.com

Build a cart and checkout

# Discover a merchant's UCP support
ucp discover --business https://shop.example.com

# Create a cart
ucp cart create --business https://shop.example.com \
  --item item_123 --quantity 1

# Add to cart
ucp cart add --business https://shop.example.com \
  --cart-id cart_abc --item item_456 --quantity 2

# Create checkout
ucp checkout create --business https://shop.example.com \
  --cart-id cart_abc

# Complete checkout (if agent has trust tier)
ucp checkout complete --business https://shop.example.com \
  --checkout-id chk_xyz \
  --payment-instrument tok_xxx

Agent profile

Your agent needs a profile hosted at a well-known URL. This is how merchants verify you and apply rate limits:

{
  "name": "My Shopping Agent",
  "version": "1.0.0",
  "capabilities": [
    "dev.ucp.shopping.checkout",
    "dev.ucp.shopping.catalog"
  ],
  "trust_tier": "standard"
}

Building an MCP Server

If you are a merchant, expose your UCP capabilities as an MCP server. This makes your store compatible with Claude, Cursor, and any MCP-compatible agent framework.

Basic MCP server with UCP

const { Server } = require("@modelcontextprotocol/sdk/server");

const server = new Server({
  name: "my-store-ucp",
  version: "1.0.0"
});

// Register UCP tools
server.tool("catalog_search", {
  description: "Search product catalog",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string" },
      limit: { type: "number" }
    }
  }
}, async (params) => {
  const results = await searchProducts(params.query, params.limit);
  return {
    content: [{
      type: "application/json",
      data: results
    }]
  };
});

server.tool("checkout_create", {
  description: "Create a UCP checkout session",
  inputSchema: {
    type: "object",
    properties: {
      line_items: { type: "array" }
    }
  }
}, async (params, meta) => {
  // Verify agent profile from meta.ucp-agent.profile
  const agentProfile = meta?.ucp_agent?.profile;
  const checkout = await createCheckout(params, agentProfile);
  return {
    content: [{
      type: "application/json",
      data: checkout
    }]
  };
});

// Expose at POST /mcp endpoint
server.listen(8080);

Profile declaration

In your /.well-known/ucp profile, declare the MCP transport:

{
  "ucp": {
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-04-08",
          "transport": "mcp",
          "endpoint": "https://your-store.com/ucp/mcp",
          "schema": "https://ucp.dev/.../mcp.openrpc.json"
        }
      ]
    }
  }
}

A2A Delegation

Agent-to-Agent Protocol lets one agent delegate a shopping sub-task to another. UCP has native A2A support:

1. Agent A receives a shopping request from the user
2. Agent A delegates the checkout sub-task to Agent B (which has a higher trust tier)
3. Agent B handles credential handoff and authorization scope
4. Agent B completes the checkout
5. Agent A receives the result and informs the user

// A2A delegation in your profile
{
  "ucp": {
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-04-08",
          "transport": "a2a",
          "endpoint": "https://your-agent.com/.well-known/agent-card.json"
        }
      ]
    }
  }
}

Agent Inference

A commerce agent needs an LLM to understand user intent, manage multi-turn conversations, and make UCP API calls. The inference provider matters for speed and cost.

// Point your agent at gateway.fast
const client = new OpenAI({
  apiKey: proces...KEY,
  baseURL: "https://api.gateway.fast/v1"
});

Putting It All Together

A production commerce agent architecture:

1. Inference: gateway.fast (or any OpenAI-compatible endpoint) for fast LLM responses
2. UCP skill: The ucp-cli skill teaches the agent how to shop via UCP
3. Discovery: Agent fetches /.well-known/ucp from target merchants
4. Negotiation: Agent and merchant auto-negotiate capabilities
5. Shopping: Agent uses catalog search, cart, checkout tools
6. Escalation: When needed, agent presents continue_url to buyer
7. Post-purchase: Agent monitors order via webhooks and get_order