⚡ FastUCP Integration Guide

What is FastUCP?

FastUCP is a Python framework that makes building UCP-compliant merchant servers simple. Built on top of FastAPI, it handles all the protocol complexity so you can focus on your business logic.

Installation

FastUCP requires Python 3.10 or higher. Install via pip or uv:

# Using pip
pip install fastucp-python

# Using uv (Recommended)
uv add fastucp-python

Quick Start

Here's a minimal UCP merchant server that sells a single item:

# main.py
from fastucp import FastUCP
from fastucp.builders import CheckoutBuilder
from fastucp.types import CheckoutCreateRequest

# 1. Initialize the App
app = FastUCP(
    title="My Store",
    base_url="http://localhost:8000"
)

# 2. Define checkout endpoint
@app.checkout("/checkout-sessions")
def create_session(payload: CheckoutCreateRequest):
    cart = CheckoutBuilder(app, session_id="session_123")
    
    cart.add_item(
        item_id="sku_001",
        title="AI Commerce T-Shirt",
        price=2500,  # $25.00 in cents
        quantity=1,
        img_url="https://example.com/shirt.jpg"
    )
    
    return cart.build()

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8000)

Run the server:

python main.py

Your server is now live with these endpoints:

🔍 Test Your FastUCP Server

Once your server is running, validate it using UCP Tools to ensure full compliance:

What We Check

• Discovery Profile: Is /.well-known/ucp accessible and valid?
• Capabilities: Are checkout, order, and fulfillment capabilities declared?
• Service Bindings: Are REST/MCP endpoints properly configured?
• Payment Handlers: Are payment methods correctly specified?
• Schema Compliance: Does the profile match UCP specification?

Adding Capabilities

FastUCP automatically registers capabilities when you use decorators:

# Checkout capability (auto-registered)
@app.checkout("/checkout-sessions")
def create_checkout(payload):
    ...

# Update checkout
@app.update_checkout("/checkout-sessions/{id}")
def update_checkout(id: str, payload):
    ...

# Complete checkout → Order capability (auto-registered)
@app.complete_checkout("/checkout-sessions/{id}/complete")
def complete_checkout(id: str, payload):
    ...

Each decorator automatically adds the corresponding capability to your /.well-known/ucp manifest.

Payment Handlers

FastUCP includes presets for common payment methods:

from fastucp.presets import GooglePay

app.add_payment_handler(
    GooglePay(
        merchant_id="your_merchant_id",
        gateway="stripe",
        gateway_merchant_id="your_stripe_id"
    )
)

This automatically adds the payment handler to your discovery profile.

Validation Tips

Checklist for UCP Compliance

1. ✅ Set correct base_url for your environment
2. ✅ Define at least one checkout endpoint using @app.checkout()
3. ✅ Add payment handlers if accepting payments
4. ✅ Test with UCP Tools validator before going live
5. ✅ Use AI Agent Simulator to verify agent compatibility

🤖 Test with AI Agent Simulator

UCP Tools includes an AI Agent Simulator that tests how AI shopping agents will interact with your FastUCP server. It simulates the full discovery and checkout flow.

Resources

• FastUCP GitHub Repository
• FastUCP on PyPI
• Official UCP Specification
• UCP Learning Center