How do I use ucp-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ucp-mcp-server Find out what the flower shop at http://flowers.example.com supports" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

ucp-mcp-server

by nguthrie

Overview Schema Source Related Servers Discussions Admin

Python

Remote

ucp-mcp-server

Let AI assistants shop. An MCP server that gives Claude, Cursor, and any MCP-compatible AI the ability to interact with UCP-enabled merchants.

UCP (Universal Commerce Protocol) is Google's new open standard for agentic commerce, backed by Shopify, Stripe, Visa, Mastercard, Target, Walmart, and 20+ partners.
MCP (Model Context Protocol) is the standard for giving AI assistants access to tools.
This project connects them.

What Can It Do?

Tool	Description
`ucp_discover`	Find out what a merchant supports (capabilities, payment methods)
`ucp_checkout_create`	Start a purchase (add items to cart, set buyer info)
`ucp_checkout_update`	Apply discount codes to an existing checkout
`ucp_checkout_set_fulfillment`	Set up shipping (auto-selects address and delivery option)
`ucp_checkout_complete`	Complete the purchase by submitting payment

Your AI assistant gets structured, type-safe access to the entire UCP shopping flow. No scraping, no browser automation, no brittle hacks.

Related MCP server: Maple Cart MCP

Quick Start

Install

pip install ucp-mcp-server

Or with uv:

uv pip install ucp-mcp-server

Use with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ucp-shopping": {
      "command": "ucp-mcp-server"
    }
  }
}

Use with Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "ucp-shopping": {
      "command": "ucp-mcp-server"
    }
  }
}

Run Directly

# As a module
python -m ucp_mcp_server

# Or via the entry point
ucp-mcp-server

Tools Reference

`ucp_discover`

Discover what a UCP merchant supports before shopping.

Arguments:
  merchant_url (str): Base URL of a UCP-enabled merchant

Returns:
  capabilities: List of supported UCP capabilities (checkout, discount, fulfillment)
  payment_handlers: Accepted payment methods (Shop Pay, Google Pay, etc.)
  ucp_version: Protocol version the merchant implements

`ucp_checkout_create`

Create a new shopping cart / checkout session.

Arguments:
  merchant_url (str): Base URL of the merchant
  items (list): Items to buy, each with "id" and "quantity"
  buyer_name (str): Full name of the buyer
  buyer_email (str): Email address
  currency (str): Currency code (default: "USD")

Returns:
  checkout_id: Session ID for tracking this purchase
  status: Current checkout status
  total: Total price in smallest currency unit (cents)
  subtotal: Subtotal before discounts
  line_items: What's in the cart

`ucp_checkout_update`

Apply discount codes or modify an existing checkout.

Arguments:
  merchant_url (str): Base URL of the merchant
  checkout_id (str): The checkout session to update
  discount_codes (list[str]): Promo codes to apply

Returns:
  checkout_id: Session ID
  total: Updated total after discounts
  discount_applied: How much was saved
  discounts: Details of applied discounts

`ucp_checkout_set_fulfillment`

Set up shipping for a checkout. Automatically selects the first available address and delivery option.

Arguments:
  merchant_url (str): Base URL of the merchant
  checkout_id (str): The checkout session

Returns:
  checkout_id: Session ID
  status: Current status
  total: Updated total (may include shipping costs)
  fulfillment: Details of selected shipping method

`ucp_checkout_complete`

Complete a checkout by submitting payment. This finalizes the purchase and returns an order ID.

Arguments:
  merchant_url (str): Base URL of the merchant
  checkout_id (str): The checkout session to complete
  payment_handler_id (str): Payment handler to use (from ucp_discover)
  card_token (str): Payment token from the provider
  card_brand (str): Card brand (e.g., "Visa")
  card_last_digits (str): Last 4 digits of the card

Returns:
  checkout_id: Session ID
  status: "complete" or "completed"
  total: Final amount charged
  order_id: Order ID for tracking
  order_url: Permalink to the order

Example Conversation

You: "Find out what the flower shop at http://flowers.example.com supports"
Claude: calls ucp_discover "This merchant supports checkout, discounts, and fulfillment tracking. They accept Shop Pay and Google Pay."
You: "Buy 2 bouquets of roses for me"
Claude: calls ucp_checkout_create "I've created a checkout for 2 Bouquet of Red Roses. Total: $70.00. Would you like to proceed?"
You: "Try the code 10OFF first"
Claude: calls ucp_checkout_update "Applied 10OFF - saved $7.00! New total: $63.00."

Why This Exists

Every AI app is going to need shopping capabilities. UCP standardizes how merchants expose commerce APIs. MCP standardizes how AI assistants use tools. This project is the bridge.

Without this, connecting AI to commerce means:

Scraping websites (brittle, breaks constantly)
Building custom integrations per merchant (doesn't scale)
Browser automation (slow, unreliable, expensive)

With UCP + MCP:

One protocol, every merchant
Structured data in, structured data out
Works with any MCP-compatible AI assistant

Development

# Clone the repo
git clone https://github.com/nguthrie/ucp-mcp-server.git
cd ucp-mcp-server

# Install dependencies
uv sync --extra dev

# Run tests
uv run pytest -v

# Run integration tests (requires a live UCP server on port 8182)
uv run pytest -v -m integration --run-integration

Project Structure

ucp-mcp-server/
├── src/ucp_mcp_server/
│   ├── __init__.py        # Package version
│   ├── __main__.py        # python -m entry point
│   ├── server.py          # MCP server + tool definitions
│   ├── ucp_client.py      # HTTP client for UCP APIs
│   └── models.py          # Pydantic models for UCP data
└── tests/
    ├── conftest.py         # Test fixtures with mock UCP responses
    ├── test_discovery.py   # Discovery tool tests
    ├── test_checkout.py    # Checkout tool tests
    ├── test_errors.py      # Error handling tests
    └── test_integration.py # Live server integration tests

Roadmap

Merchant capability discovery
Checkout session creation
Discount code application
Fulfillment / shipping setup
Purchase completion / payment submission
Order fulfillment tracking
Returns and exchanges
Multi-merchant comparison shopping
Hosted managed version (so you don't have to self-host)

Resources

UCP Specification - The Universal Commerce Protocol
UCP GitHub
UCP Python SDK
MCP Documentation - Model Context Protocol
Google's UCP Blog Post

License

MIT

Available Tools

5 tools

ucp_checkout_completeA

Complete a checkout session by submitting payment. This finalizes the purchase.

Args: merchant_url: The base URL of the UCP-enabled merchant checkout_id: The ID of the checkout session to complete payment_handler_id: The ID of the payment handler to use (from ucp_discover) card_token: Payment token from the payment provider card_brand: Card brand (e.g., Visa, Mastercard) card_last_digits: Last 4 digits of the card

Returns: Dictionary containing: - checkout_id: The checkout session ID - status: Final status (should be 'complete') - total: Final total charged - order_id: The order ID for tracking - order_url: Permalink to the order

Inputs: merchant_url (required), checkout_id (required), payment_handler_id, card_token, +2 more. Returns: object

ucp_checkout_createB

Create a new checkout session with a UCP merchant.

Args: merchant_url: The base URL of the UCP-enabled merchant items: List of items to purchase, each with 'id' and 'quantity' buyer_name: Full name of the buyer buyer_email: Email address of the buyer currency: Currency code (default: USD)

Returns: Dictionary containing: - checkout_id: The ID of the created checkout session - status: Current status of the checkout - total: Total amount in smallest currency unit (e.g., cents) - line_items: List of items in the cart

Inputs: merchant_url (required), items (required), buyer_name (required), buyer_email (required), +1 more. Returns: object

ucp_checkout_set_fulfillmentA

Set up shipping/fulfillment for a checkout. Automatically selects the first available shipping address and delivery option. Must be called before completing checkout if the merchant requires fulfillment.

Args: merchant_url: The base URL of the UCP-enabled merchant checkout_id: The ID of the checkout session

Returns: Dictionary containing: - checkout_id: The checkout session ID - status: Current status - total: Updated total (may include shipping costs) - fulfillment: Details of selected shipping method

Inputs: merchant_url (required), checkout_id (required). Returns: object

ucp_checkout_updateA

Update an existing checkout session (e.g., apply discount codes).

Args: merchant_url: The base URL of the UCP-enabled merchant checkout_id: The ID of the checkout session to update discount_codes: List of discount/promo codes to apply

Returns: Dictionary containing updated checkout information: - checkout_id: The checkout session ID - status: Current status - total: Updated total amount - discount_applied: Amount discounted - discounts: Details of applied discounts

Inputs: merchant_url (required), checkout_id (required), discount_codes. Returns: object

ucp_discoverA

Discover a merchant's UCP capabilities and supported payment methods.

Args: merchant_url: The base URL of the UCP-enabled merchant (e.g., http://localhost:8182)

Returns: Dictionary containing: - capabilities: List of UCP capabilities the merchant supports - payment_handlers: List of payment methods accepted - ucp_version: The UCP protocol version

Inputs: merchant_url (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-05-28 21:15 across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: discover capabilities, create checkout, update with discounts, set fulfillment, and complete payment. No overlap in functionality.

Naming Consistency5/5

All tools follow the 'ucp_verb_noun' pattern with consistent snake_case and prefix, making them predictable and easy to distinguish.

Tool Count5/5

Five tools cover the essential checkout steps without unnecessary bloat. The count is well-scoped for the domain.

Completeness4/5

The set covers the full checkout lifecycle: discovery, creation, discount updates, fulfillment setup, and payment completion. Missing cancellation or refund capabilities but core flow is complete.

Maintenance

ActivityInactive

ResponsivenessOutdated data

Resources

Related MCP Connectors

Agent CheckoutA
com.agentcheckoutapi
AI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
E-commerce & Retail Search Payments & Billing
81
https://agentcheckoutapi.com/mcp
FinCore Agentic CommerceA
io.github.athenalion
Agentic commerce with 58 MCP tools for product search, checkout, A2A negotiation, C-Suite analytics.
E-commerce & Retail Autonomous Agents
2
https://api.aiproductscout.shop/fincore/mcp
Trusteed Agentic CommerceA
xyz.trusteed
Agentic commerce gateway: discovery, search, checkout across Shopify/Woo/Odoo/PrestaShop with UCP, ACP, AP2, X402. Checkout rules for agents, and trust receipts.
App Automation Cryptocurrency E-commerce & Retail
2
https://trusteed.xyz/demo-store/mcp
BotFriendlyA
xyz.botfriendly
Directory of APIs, merchants, and tools AI agents can actually use.
Search Developer Tools
71
https://mcp.botfriendly.xyz

Related MCP Servers

Shopping MCP Server (Amazon +
E-commerce & Retail App Automation
sachinparyani
A
license
Not graded
quality
D
maintenance
Enables AI assistants to search products, manage shopping carts, place orders, and retrieve order history from Amazon and Target accounts.
Updated a year ago (2025-11-04 01:42 UTC)
3
MIT
Maple Cart MCP
E-commerce & Retail Payments & Billing
mehakchawla1234
F
license
Not graded
quality
D
maintenance
Enables e-commerce shopping assistant capabilities including product search, cart management, payment processing, and order fulfillment via MCP tools.
Updated 10 months ago (2026-01-24 17:34 UTC)
-
Commerce MCP Server
E-commerce & Retail Search Autonomous Agents
NewPlanetWW
F
license
Not graded
quality
D
maintenance
Enables AI agents to browse product catalogs, search products with filters, and initiate checkouts, generating order summaries and checkout URLs.
Updated 6 months ago (2026-05-24 00:43 UTC)
-
clishop
E-commerce & Retail App Automation
DavooxBv2
A
license
Not graded
quality
D
maintenance
Enables AI agents and humans to search products across multiple stores, compare prices, and place real orders directly from the terminal using 46 MCP tools.
Updated 7 months ago (2026-04-06 12:17 UTC)
98 npm
2
MIT

ucp-mcp-server

What Can It Do?

Quick Start

Install

Use with Claude Desktop

Use with Cursor

Run Directly

Tools Reference

ucp_discover

ucp_checkout_create

ucp_checkout_update

ucp_checkout_set_fulfillment

ucp_checkout_complete

Example Conversation

Why This Exists

Development

Project Structure

Roadmap

Resources

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Shopping MCP Server (Amazon +

Maple Cart MCP

Commerce MCP Server

clishop

`ucp_discover`

`ucp_checkout_create`

`ucp_checkout_update`

`ucp_checkout_set_fulfillment`

`ucp_checkout_complete`