How to Implement a UCP Endpoint on Your Store

The Universal Commerce Protocol (UCP) enables AI agents to discover, browse, and transact with your store programmatically. This guide walks you through implementing a UCP endpoint from scratch — from the manifest to MCP tools to getting listed in the UCP Registry.

#What You'll Build

By the end of this guide, your store will:

• Serve a UCP manifest at /.well-known/ucp that AI agents can discover
• Expose an MCP (Model Context Protocol) endpoint for product search, checkout, and fulfillment
• Be verifiable by the UCP Registry and compatible with any UCP-enabled shopping agent

#Prerequisites

You'll need a publicly accessible web server with HTTPS. If you're on Shopify, WooCommerce, or BigCommerce, check the Plugins directory — there are platform-specific implementations that handle everything automatically. Shopify merchants should also see our dedicated Shopify UCP setup guide.

#Step 1: Create the UCP Manifest

The manifest is a JSON document served at /.well-known/ucp on your domain. This is how agents discover what your store supports.

{
  "ucp": {
    "version": "2026-01-23",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-01-23",
          "spec": "https://ucp.dev/specification/overview/",
          "transport": "mcp",
          "endpoint": "https://yourstore.com/api/ucp/mcp",
          "schema": "https://ucp.dev/services/shopping/openrpc.json"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-01-23",
          "spec": "https://ucp.dev/specification/checkout",
          "schema": "https://ucp.dev/schemas/shopping/checkout.json"
        }
      ],
      "dev.ucp.shopping.fulfillment": [
        {
          "version": "2026-01-23",
          "spec": "https://ucp.dev/specification/fulfillment",
          "schema": "https://ucp.dev/schemas/shopping/fulfillment.json",
          "extends": "dev.ucp.shopping.checkout"
        }
      ],
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-01-23",
          "spec": "https://ucp.dev/specification/discount",
          "schema": "https://ucp.dev/schemas/shopping/discount.json",
          "extends": "dev.ucp.shopping.checkout"
        }
      ]
    }
  }
}

Key things to note:

• Version: Use the latest spec version (2026-01-23 at time of writing)
• Services: The dev.ucp.shopping service is the core shopping service. You declare which transports are available — mcp for MCP protocol, embedded for embedded checkout
• Capabilities: Declare which commerce operations your store supports. Start with checkout, then add fulfillment and discount support as you build them out
• Endpoint: The URL where agents will send MCP requests

#Step 2: Implement the MCP Endpoint

Your MCP endpoint receives JSON-RPC 2.0 requests over HTTP POST. Agents will first initialize a session, then discover your tools, and finally call them.

#The Initialize Handshake

When an agent connects, it sends an initialize request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "clientInfo": { "name": "shopping-agent", "version": "1.0" },
    "capabilities": {}
  }
}

Your server should respond with its own capabilities:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "serverInfo": { "name": "yourstore-ucp", "version": "1.0" },
    "capabilities": { "tools": {} }
  }
}

#Declare Your Tools

When an agent sends tools/list, return the tools your store supports:

{
  "result": {
    "tools": [
      {
        "name": "search_shop_catalog",
        "description": "Search products in the store catalog",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string", "description": "Search query" },
            "limit": { "type": "integer", "default": 10 }
          },
          "required": ["query"]
        }
      },
      {
        "name": "get_product",
        "description": "Get detailed product information",
        "inputSchema": {
          "type": "object",
          "properties": {
            "product_id": { "type": "string" }
          },
          "required": ["product_id"]
        }
      },
      {
        "name": "create_checkout",
        "description": "Create a checkout session",
        "inputSchema": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "variant_id": { "type": "string" },
                  "quantity": { "type": "integer" }
                }
              }
            }
          },
          "required": ["items"]
        }
      }
    ]
  }
}

#Handle Tool Calls

When an agent calls tools/call, route to the appropriate handler:

// Express.js example
app.post('/api/ucp/mcp', async (req, res) => {
  const { method, params, id } = req.body;

  switch (method) {
    case 'initialize':
      return res.json({
        jsonrpc: '2.0', id,
        result: {
          protocolVersion: '2025-03-26',
          serverInfo: { name: 'my-store', version: '1.0' },
          capabilities: { tools: {} }
        }
      });

    case 'tools/list':
      return res.json({
        jsonrpc: '2.0', id,
        result: { tools: getToolDefinitions() }
      });

    case 'tools/call':
      const result = await handleToolCall(params.name, params.arguments);
      return res.json({
        jsonrpc: '2.0', id,
        result: { content: [{ type: 'text', text: JSON.stringify(result) }] }
      });
  }
});

#Step 3: Implement Product Search

The search_shop_catalog tool is the most important — it's what agents call first. Return structured product data:

{
  "products": [
    {
      "title": "Classic Running Shoe",
      "url": "https://yourstore.com/products/classic-runner",
      "image_url": "https://cdn.yourstore.com/classic-runner.jpg",
      "product_type": "Footwear",
      "price": {
        "amount": 12000,
        "currency": "USD"
      },
      "variants": [
        { "id": "var_001", "title": "Size 10 / Black", "available": true },
        { "id": "var_002", "title": "Size 11 / Black", "available": true }
      ]
    }
  ]
}

Prices should be in the smallest currency unit (cents for USD). Include variant IDs so agents can add specific items to cart.

#Step 4: Test Your Implementation

#Manual Testing with cURL

# Test manifest discovery
curl -s https://yourstore.com/.well-known/ucp | jq .

# Test MCP initialization
curl -X POST https://yourstore.com/api/ucp/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "clientInfo": {"name": "test", "version": "1.0"},
      "capabilities": {}
    }
  }' | jq .

# Test tool discovery
curl -X POST https://yourstore.com/api/ucp/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }' | jq .

#Automated Testing with UCP Playground

The UCP Playground runs a comprehensive benchmark against your endpoint — testing tool discovery, product search quality, response times, and checkout flows. It gives you a grade from A to F and detailed feedback on what to improve.

#Verify on UCP Registry

Submit your domain to the UCP Registry. Our crawler will verify your manifest, test your MCP endpoint, and list your store in the directory. Verified merchants get:

• A public profile page with your capabilities and benchmark scores
• Inclusion in the Product Discovery index so agents can find your products
• A badge and widget you can embed on your store
• Monitoring and uptime tracking

#Step 5: Add Payment Handlers (Optional)

For full checkout support, declare payment handlers in your manifest:

{
  "payment_handlers": {
    "com.google.pay": [
      {
        "id": "gpay",
        "version": "2026-01-11",
        "config": {
          "merchant_info": {
            "merchant_name": "Your Store",
            "merchant_id": "YOUR_GOOGLE_PAY_ID"
          },
          "allowed_payment_methods": [
            {
              "type": "CARD",
              "parameters": {
                "allowed_card_networks": ["VISA", "MASTERCARD", "AMEX"]
              }
            }
          ]
        }
      }
    ]
  }
}

#Common Mistakes

• Wrong manifest path: Use /.well-known/ucp (not /.well-known/ucp.json)
• HTTP instead of HTTPS: Always serve over HTTPS. HTTP manifests may not be discoverable
• Missing CORS headers: If agents call your MCP endpoint from browsers, you'll need appropriate CORS headers
• Prices as floats: Use integer amounts in smallest currency unit (cents). 1299 not 12.99
• Missing variant IDs: Agents need variant IDs to add items to cart. Always include them in product responses
• Slow responses: Agents expect sub-second responses. If your search takes more than 2 seconds, agents will time out

#What's Next

Once your endpoint is live and verified:

1. Monitor performance — Check your merchant profile on the registry for response time trends and uptime data
2. Improve your benchmark score — Run the UCP Playground benchmark to identify areas for improvement
3. Add more capabilities — Start with search and checkout, then add fulfillment and discount support
4. Track agent traffic — Watch your server logs for MCP requests from shopping agents

---

For the broader context on why UCP adoption matters, read why UCP matters for e-commerce in 2026. To understand how payments work in the UCP ecosystem, see our payment handlers overview. And if you want to get your business listed after implementation, follow our guide on adding your business to the UCP ecosystem.

---

Have questions about implementing UCP? Contact us or check the Developers page for API documentation.