Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@UCP MCP Storefront search for wireless headphones"
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.
A UCP-compliant MCP storefront server that exposes a product catalog as MCP tools. Each tool maps to a real UCP capability (Catalog Search & Lookup, Cart Building, Checkout, Order Management), and every tool's output matches the corresponding UCP schema (version 2026-04-08).
UCP is transport-agnostic and explicitly supports MCP as a transport alongside REST and A2A — so "a UCP storefront exposed over MCP" is on-spec.
All prices are integers in cents (e.g. 1999 = $19.99). Never floats for money.
UCP version 2026-04-08 — date-based versioning per the UCP spec.
Payment is always mocked — no real credentials, ever.
Related MCP server: SlimWeb Client MCP
# Install dependencies
uv sync
# Run tests
uv run pytest
# Start the server (stdio transport)
uv run python -m ucp_mcp_storefront.serverTool | UCP Capability | Description |
|
| Search products by query, max price (cents), and/or category |
|
| Get full product details by ID |
search(query, max_price?, category?)query (string, required): Free-text search matching title, description, and tags.
max_price (int, optional): Maximum price in cents (e.g. 10000 = $100.00).
category (string, optional): Filter by tag/category.
Returns a UCP search_response with matching products.
get_product(product_id)product_id (string, required): Product identifier (e.g. "prod_001").
Returns a UCP get_product_response with full product detail including variants and pricing.
Add to your claude_desktop_config.json:
{
"mcpServers": {
"ucp-storefront": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/ucp-mcp-storefront", "python", "-m", "ucp_mcp_storefront.server"]
}
}
}# Install and run the MCP inspector
npx @modelcontextprotocol/inspector uv run python -m ucp_mcp_storefront.serverPrompt: "Find running shoes under $100"
The agent calls search(query="running shoes", max_price=10000) and gets back UCP-shaped results with products, price ranges, variants, and availability status.
├── src/ucp_mcp_storefront/ # Server source code
│ ├── server.py # FastMCP app; registers all tools
│ ├── catalog.py # Load + query the fake catalog
│ ├── cart.py # In-memory cart store
│ ├── checkout.py # UCP checkout object (mocked payment)
│ ├── ucp_mapping.py # Internal objects → UCP-shaped dicts
│ └── models.py # Pydantic models mirroring UCP fields
├── data/products.json # Fake catalog (25 items, prices in cents)
├── schemas/resolved/ # Resolved UCP JSON Schemas (for tests)
├── tests/ # pytest test suite
├── scripts/ # Schema resolution and utilities
└── docs/ # Architecture and UCP mapping docsM0 — Scaffold + fake catalog
M1 — Read tools (search, get_product)
M2 — Cart tools (create_cart, add_to_cart, view_cart)
M3 — UCP conformance for cart/line-item shapes
M4 — Checkout tool (UCP checkout object + mock payment)
M5 — Polish & proof
Add a product to an existing cart.
Args: cart_id: The cart identifier (e.g. "crt_..."). product_id: The product identifier (e.g. "prod_001"). quantity: Number of units to add (default 1).
Validates that the product exists and has sufficient inventory. Returns the updated UCP cart, or an error message on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| quantity | No | ||
| product_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses validation (product existence, inventory) and return behavior (updated cart or error). It implies mutation but doesn't detail side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, followed by parameter list, then behavior. Two sentences for args, one for validation, one for return. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description mentions return type (updated UCP cart or error) and covers key validation. Could be more complete by specifying the structure of the cart object or error details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates well. It explains each parameter: cart_id and product_id with example formats, quantity with default. Adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a product to an existing cart,' using a specific verb and resource. It distinguishes itself from sibling tools like create_cart (creating new) and view_cart (viewing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the cart already exists and product is known, but does not explicitly state when to use vs alternatives or when not to use. No exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new empty shopping cart.
Returns a UCP cart response with a unique cart ID (crt_...).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses the creation of a new empty cart and the return of a unique ID. With no annotations, the description carries the full burden and handles it well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no unnecessary words. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description is complete: it explains what the tool does and what it returns. Nothing is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema coverage is 100%. The description adds no parameter info, but none is needed. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new empty shopping cart' and specifies the return value (unique cart ID). It distinguishes well from siblings like add_to_cart and view_cart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is clear: use this to create a new cart before adding items. However, it does not explicitly state when not to use or mention alternatives, though siblings provide implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full product details by ID.
Args: product_id: The product identifier (e.g. "prod_001").
Returns a UCP get_product response, or an error message if not found.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns a UCP get_product response or an error if not found. It does not mention permissions or side effects, but as a read-only operation, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences plus an args description. It is front-loaded with the main purpose and includes essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 required parameter, no output schema), the description fully explains the input, return value, and error case. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must add meaning. It provides an example format ('prod_001') and explains that the product_id is an identifier. This goes beyond the schema's generic title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full product details by ID,' specifying the verb (get) and resource (product details). This distinguishes it from sibling tools like search (searching for products) and add_to_cart (adding items to cart).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use: when you have a product ID and need full details. It provides an example ID format. However, it does not explicitly state alternatives or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the product catalog.
Args: query: Free-text search query (matches title, description, tags). max_price: Maximum price in cents (e.g. 10000 = $100.00). Optional. category: Filter by tag/category. Optional.
Returns a UCP catalog search response with matching products.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| category | No | ||
| max_price | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It explains that the tool searches by title, description, and tags, and returns matching products. However, it does not mention API limitations, authentication needs, or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose. The argument list is clearly formatted. However, it could be slightly more streamlined without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description mentions the return type ('UCP catalog search response with matching products'), which gives a good overview. Given the tool's simplicity, this is largely complete, though more detail on pagination or sorting could help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully explains each parameter: query (free-text, matches fields), max_price (in cents with example), and category (optional filter). This adds significant meaning beyond the schema names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search the product catalog.' with a specific verb and resource. The sibling tools (add_to_cart, create_cart, get_product, view_cart) serve different purposes, so the search tool is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching the product catalog but does not explicitly state when to use this tool versus alternatives or provide any exclusions. The sibling tools have distinct names, but no direct comparison is made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
View the current contents of a cart.
Args: cart_id: The cart identifier (e.g. "crt_...").
Returns the UCP cart with line items and running totals (in cents).
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It states this is a view operation (implied read-only) and describes return content (line items, running totals). However, it lacks details on side effects, prerequisites, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with minimal waste. It front-loads the purpose, then describes arguments and return values efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description adequately covers purpose, parameter semantics, and return value. It is missing potential error scenarios or behavior when cart_id is invalid, but overall is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains the cart_id parameter with an example format ('crt_...'), adding meaning beyond the schema's type-only definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'View the current contents of a cart,' using a specific verb and resource. It distinguishes from sibling tools like add_to_cart, create_cart, get_product, and search by focus on viewing a cart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. While the sibling tools are listed in context, the description itself offers no usage context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_to_cartcreate_cartget_productsearchview_cartScored across 5 tools
Each tool has a clear, distinct purpose: cart creation, item addition, cart viewing, product retrieval, and catalog search. No two tools overlap in functionality.
All tool names follow a consistent verb_noun pattern in snake_case (add_to_cart, create_cart, get_product, search, view_cart). The naming is predictable and easy for an agent to follow.
With exactly 5 tools, the surface is well-scoped for a storefront domain. Each tool serves a necessary function without redundancy or bloat.
Core cart and product operations are covered. However, missing cart update (quantity change), remove item, or checkout functionality leaves minor gaps that agents might need to work around.
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
Remote MCP server for product discovery catalog and retrieving product details.
Federated commerce search across independent WooCommerce merchants. Keyless, read-only MCP server.
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
