How to Implement UCP Checkout: A Developer's Guide

Before You Start

This guide walks through implementing UCP checkout on a custom e-commerce backend. If you're on Shopify, you don't need this; UCP is built into the platform. See our Shopify-specific guide instead.

For everyone else: implementing UCP is a moderate engineering effort. The core idea is straightforward: you serve a /.well-known/ucp JSON manifest that tells agents where to find your MCP and/or REST endpoints, then expose those endpoints so agents can browse your catalog and complete purchases.

Prerequisites:

A working e-commerce backend with a product catalog and checkout flow
A payment handler that supports UCP (Stripe, Adyen, etc.; see our payment handlers guide)
Node.js 20+ or Python 3.11+
Familiarity with the UCP specification and MCP (Model Context Protocol)

Resources:

UCP JavaScript SDK: TypeScript/JavaScript
UCP Python SDK: Python
UCP Schema definitions: JSON schemas
Sample implementations: Reference examples

Step 1: Serve the UCP Manifest

The entry point for any UCP integration is the /.well-known/ucp manifest. This JSON file tells agents what your store supports and where to find your endpoints.

Step 2: Expose an MCP Server

UCP uses MCP (Model Context Protocol) as the primary interface for agent interactions. Your MCP server exposes tools that agents can call, like search_products, get_product, and create_checkout. Install the MCP SDK:

npm install @modelcontextprotocol/sdk zod

Here's a combined setup showing both the manifest and MCP server:

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { z } from 'zod';

const app = express();

// Step 1: Serve the UCP discovery manifest
app.get('/.well-known/ucp', (req, res) => {
  res.json({
    name: 'Your Store Name',
    description: 'A brief description of your store',
    url: 'https://yourstore.com',
    mcp_endpoint: 'https://yourstore.com/mcp',
    capabilities: ['product_discovery', 'checkout', 'order_management'],
    payment_handlers: ['com.stripe'],
    supported_currencies: ['USD'],
  });
});

// Step 2: Create the MCP server with shopping tools
const server = new McpServer({
  name: 'Your Store UCP Server',
  version: '1.0.0',
});

The manifest at /.well-known/ucp is how agents discover your store. The mcp_endpoint field tells them where to connect for shopping interactions.

Step 3: Define Your MCP Tools

Your MCP server exposes tools that agents call to browse your catalog and initiate purchases. Here's how to map your product data:

// Product search tool
server.tool(
  'search_products',
  'Search the product catalog',
  {
    query: z.string().describe('Search terms'),
    category: z.string().optional(),
    max_price: z.number().optional().describe('Max price in cents'),
    limit: z.number().default(20),
  },
  async ({ query, category, max_price, limit }) => {
    const products = await yourDB.products.search({
      text: query, category, maxPrice: max_price, limit,
    });
    return {
      content: [{ type: 'text', text: JSON.stringify(products.map(mapToUCPProduct)) }],
    };
  },
);

// Product detail tool
server.tool(
  'get_product',
  'Get detailed product information',
  { product_id: z.string() },
  async ({ product_id }) => {
    const product = await yourDB.products.findById(product_id);
    if (!product) {
      return { content: [{ type: 'text', text: 'Product not found' }], isError: true };
    }
    return {
      content: [{ type: 'text', text: JSON.stringify(mapToUCPProduct(product)) }],
    };
  },
);

function mapToUCPProduct(product: any) {
  return {
    id: product.id,
    title: product.name,
    description: product.description,
    price: { amount: product.priceInCents, currency: 'USD' },
    variants: product.variants.map((v: any) => ({
      id: v.id,
      attributes: v.attributes, // { size: 'M', color: 'Blue' }
      price: { amount: v.priceInCents, currency: 'USD' },
      available: v.inventoryCount > 0,
    })),
    images: product.images.map((img: any) => ({ url: img.url, alt: img.altText })),
    shipping: {
      estimatedDays: product.shippingEstimate,
      freeAbove: product.freeShippingThreshold,
    },
  };
}

The most important thing here is accuracy. Agents will make purchasing decisions based on this data. If your inventory count is stale, an agent might try to buy an out-of-stock item. If your prices are wrong, you'll have angry customers. Real-time data is not optional.

Step 4: Implement the Checkout Tool

The checkout tool lets agents initiate purchases. You handle the business logic: inventory validation, pricing, and session management:

// Checkout tool
server.tool(
  'create_checkout',
  'Create a checkout session for a product',
  {
    product_id: z.string(),
    variant_id: z.string().optional(),
    quantity: z.number().default(1),
  },
  async ({ product_id, variant_id, quantity }) => {
    const product = await yourDB.products.findById(product_id);
    const variant = variant_id
      ? product?.variants.find((v: any) => v.id === variant_id)
      : product?.variants[0];

    if (!variant || variant.inventoryCount < quantity) {
      return {
        content: [{ type: 'text', text: 'Item unavailable in requested quantity' }],
        isError: true,
      };
    }

    const session = await yourCheckoutService.createSession({
      items: [{ productId: product_id, variantId: variant.id, quantity }],
    });

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          session_id: session.id,
          total: session.total,
          checkout_url: session.confirmationUrl,
          expires_at: session.expiresAt,
        }),
      }],
    };
  },
);

// Mount MCP server on HTTP transport
app.all('/mcp', async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });
  await server.connect(transport);
  await transport.handleRequest(req, res);
});

Step 5: Run Conformance Tests

The UCP project provides a conformance test suite to validate your implementation. Clone and run it against your endpoints:

git clone https://github.com/universal-commerce-protocol/conformance.git
cd conformance
npm install
npm test -- --url https://yourstore.com

The test suite covers scenarios including:

Manifest discovery and validation
Product search with various filter combinations
Checkout session creation and edge cases
Out-of-stock handling during checkout
Price changes between discovery and checkout
Malformed request handling

Check the conformance repo for the latest test scenarios and requirements.

Step 6: Get Discovered

Once your implementation is live and passing conformance tests, agents need to find you:

The manifest does the heavy lifting. Any agent that visits https://yourstore.com/.well-known/ucp can discover your capabilities automatically.
Submit to directories. List your store on UCPList.ai and other UCP directories for additional visibility.
Register with Google Shopping. If you're already in Google Merchant Center, enabling UCP there gives you access to agents that discover merchants through Google's infrastructure.

Common Pitfalls

Stale inventory data. The number one cause of failed UCP transactions. If your inventory checks are cached or delayed, agents will attempt to purchase out-of-stock items. Use real-time inventory queries in your MCP tools.

Missing variant attributes. Agents need structured variant data to make informed choices. "Red / Large" as a variant name isn't enough; use structured attributes like { color: 'Red', size: 'Large' }.

Slow response times. Agents query multiple merchants simultaneously. If your endpoints are slow, agents will deprioritize your store. Aim for under 200ms on product search and under 500ms on checkout session creation.

Incorrect price formatting. UCP uses integer amounts in the smallest currency unit (cents for USD). A $29.99 item should be { amount: 2999, currency: 'USD' }. Getting this wrong leads to 100x pricing errors.

Not handling concurrent sessions. Agents may create multiple checkout sessions for the same consumer as they compare options. Your implementation should handle session cleanup and prevent inventory locking issues.

Debugging Tips

Test your MCP server locally using the MCP Inspector, which provides a browser-based UI for calling your tools interactively. You can also test your manifest directly:

curl https://localhost:3000/.well-known/ucp | jq .

For MCP debugging, enable verbose logging in your server to see incoming tool calls and responses during development.

Next Steps

With your UCP implementation live, consider:

Adding order management tools (returns, tracking) to your MCP server
Implementing identity linking so returning consumers get personalized results
Monitoring agent interaction patterns and optimizing your tool responses
Joining the UCP developer community for support and updates

The UCP specification is the authoritative reference for protocol details. Our developer tools directory lists additional libraries, testing tools, and integrations that can accelerate your implementation.