Running an Agent-Ready Storefront Locally with UCP Java and Spring Boot

As autonomous AI agents move from answering product questions to executing real purchases, merchants and fintech platforms face an immediate architectural bottleneck: traditional e-commerce APIs were built for custom frontends, not autonomous reasoning loops. The Universal Commerce Protocol (UCP) solves this by defining a uniform discovery mechanism (/.well-known/ucp), typed commerce schemas, and multi-transport bindings across REST, Model Context Protocol (MCP), and Agent-to-Agent (A2A).

For JVM and Spring engineering teams, UCP Java (dev.ucomprotocol:ucp-spring-boot-starter:0.2.0) brings UCP 2026-08-25 directly to Spring Boot 4—complete with Resilience4j fault tolerance, auto-configured discovery, and a stateful sample storefront application you can spin up on your laptop in seconds to test live with any AI agent.

Project Resources: Documentation (ucomprotocol.dev) · User Guide · API Reference · Javadocs · Maven Central · GitHub Repo · Agentic Protocols Hub

What the Sample Storefront Includes

Located in examples/ucp-example, the reference application wires an in-memory CommerceAdapter backed by concurrent state and automatic Resilience4j CircuitBreaker + Retry decoration. Out of the box, it implements all six UCP capabilities:

UCP Capability	Java SPI Adapter	What Agents Can Do
dev.ucp.shopping.catalog.search	CatalogAdapter	Keyword & category search across 6 seeded coffee and electronics products
dev.ucp.shopping.catalog.lookup	CatalogAdapter	Direct product lookup by ID or SKU
dev.ucp.shopping.cart	CartAdapter	Create carts, add/update/remove line items, and compute live totals
dev.ucp.shopping.checkout	CheckoutAdapter	Initiate, update, complete, or cancel UCP checkout sessions
dev.ucp.shopping.order	OrderAdapter	Convert checkouts into confirmed orders, inspect history, or cancel orders
dev.ucp.common.identity_linking	CustomerAdapter	Look up, create, and update customer profiles (seeded with cust-demo-01)

Even better, the sample storefront exposes three simultaneous agent transports so you can test whichever integration pattern your stack uses:

• UCP Discovery: GET http://localhost:8082/.well-known/ucp — canonical UCP 2026-08-25 business profile advertising capabilities and schemas.
• MCP Streamable HTTP: POST http://localhost:8082/ucp/mcp — native JSON-RPC 2.0 Model Context Protocol server exposing 16 typed commerce tools.
• REST Shopping API: http://localhost:8082/ucp/v1/* — canonical REST routes for catalogs, carts, checkout sessions, orders, and customers.
• A2A Agent Card: GET http://localhost:8082/.well-known/agent-card.json — Agent-to-Agent skill and capability metadata.

Step 1: Clone and Run the Sample App Locally

All you need is Java 17+ (the repository bundles the Gradle 9.9.1 wrapper, so no local Gradle installation is required).

git clone https://github.com/aksharprabhudesai/universal-commerce-protocol-java.git
cd universal-commerce-protocol-java

# Start the sample storefront on http://localhost:8082
./gradlew -p examples/ucp-example bootRun

In less than a second, Spring Boot starts on port 8082. Open another terminal and inspect the live UCP discovery document:

curl -s http://localhost:8082/.well-known/ucp | python3 -m json.tool

You can also run the automated end-to-end integration test suite—which exercises UCP discovery, A2A agent card inspection, a full REST purchase flow, and a multi-step MCP JSON-RPC agent checkout:

./gradlew -p examples/ucp-example test

Step 2: Connect Any AI Agent

Option A: MCP-Compatible Agents (Claude Code, Cursor, Claude Desktop, Gemini CLI, Antigravity)

Because the storefront speaks native MCP Streamable HTTP at /ucp/mcp, you can attach any MCP client directly with zero adapter glue.

For Claude Code:

claude mcp add --transport http ucp-store http://localhost:8082/ucp/mcp

Or in mcp_config.json / .cursor/mcp.json / settings.json:

{
  "mcpServers": {
    "ucp-store": {
      "url": "http://localhost:8082/ucp/mcp"
    }
  }
}

Once connected, your agent immediately discovers 16 commerce tools (search_catalog, lookup_catalog, create_cart, update_cart, create_checkout, complete_checkout, get_order, cancel_order, and more). Try prompting it in plain English:

1. "Search the UCP store for coffee equipment under $200 and show me what is in stock."
2. "Create a cart for customer cust-demo-01, add 1 conical burr grinder and 2 double-wall espresso cup sets, and confirm the total."
3. "Create a checkout session for that cart, complete the checkout, and give me the confirmed order ID."
4. "List all orders for cust-demo-01 and cancel the order we just placed."

Option B: Zero-Config Autonomous HTTP & A2A Agents

If you are building custom agents in LangChain, LangGraph, CrewAI, or any framework with an HTTP fetch tool, you do not even need to pre-register tools. Point the agent directly at the merchant discovery URL:

"Connect to http://localhost:8082/.well-known/ucp (or http://localhost:8082/.well-known/agent-card.json), discover the merchant's capabilities and transport endpoints, and purchase a wireless mechanical keyboard for customer cust-demo-01."

Option C: Test Directly from the Terminal with curl

You can also drive both MCP JSON-RPC and REST flows straight from your shell to watch how state transitions across capabilities:

# 1. Invoke MCP search_catalog over JSON-RPC 2.0
curl -s -X POST http://localhost:8082/ucp/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_catalog","arguments":{"category":"coffee"}}}' | python3 -m json.tool

# 2. Create a cart via REST (/ucp/v1)
curl -s -X POST http://localhost:8082/ucp/v1/carts \
  -H "Content-Type: application/json" \
  -d '{"customerId":"cust-demo-01","items":[{"productId":"prod-grinder-02","quantity":1},{"productId":"prod-mugs-03","quantity":2}]}'

# 3. Start and complete checkout (replace cart-1001 / chk-2001 with returned IDs)
curl -s -X POST http://localhost:8082/ucp/v1/checkout-sessions \
  -H "Content-Type: application/json" \
  -d '{"cartId":"cart-1001"}'

curl -s -X POST http://localhost:8082/ucp/v1/checkout-sessions/chk-2001/complete

Bringing UCP Java to Your Own Backend

When you are ready to expose your own catalog, cart, and payment orchestration pipelines to AI agents, add the starter from Maven Central:

dependencies {
    implementation 'dev.ucomprotocol:ucp-spring-boot-starter:0.2.0'
    implementation 'org.springframework.boot:spring-boot-starter-webmvc'
}

Implement the CommerceAdapter SPI as a Spring @Bean—returning null for any capability you do not wish to expose—and UCP Java automatically wraps your implementation with Resilience4j protection and publishes an accurate /.well-known/ucp profile.

Check out the full documentation at ucomprotocol.dev and star or fork universal-commerce-protocol-java on GitHub to start building agentic commerce on Spring Boot.