Servers Playground How we check Add a server Log in

Facet UCP Shopping

Working · 1.6 s

llc.facet/ucp-shoppingv1.0.0 Domain verified

The independent agent-commerce protocol for AI-agent checkout on any online store.

Commerce

Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://api.facet.llc/ucp/mcp

Authorization (optional)

Optional Facet KYA bearer, an ES256 JWT from the default issuer https://issuer.facet.llc (or another issuer advertised at /.well-known/agents.txt KYA-Issuers). Not required for tools/list or catalog discovery; required for gated tools/call, per the endpoint's agents.txt (MCP-Auth: kya-bearer).

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

cancel_cart

Cancel a cart. Idempotent, owner-scoped, and moves no money. REQUIRES IDENTITY plus an Idempotency-Key on a signature-required Terminal.

idstring, required

The cart id.

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

Facet UCP Shopping MCP server | mcptry

Tools (23)

cancel_cart

Cancel a cart. Idempotent, owner-scoped, and moves no money. REQUIRES IDENTITY plus an Idempotency-Key on a signature-required Terminal.

Argument	Type	Description
id*	string	The cart id.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The cart id."
    }
  }
}

cancel_checkout

Cancel a checkout session before completion, releasing its inventory hold. Idempotent, owner-scoped, and moves no money (distinct from an escrow refund). REQUIRES IDENTITY plus an Idempotency-Key on a signature-required Terminal.

Argument	Type	Description
id*	string	The checkout session id.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The checkout session id."
    }
  }
}

complete_checkout

Complete a checkout you created and place the order by submitting the buyer-signed payment credential. This is the MONEY-MOVING leg: funds capture on-chain to the merchant's pay_to (x402) or into escrow (Boson). The amount is re-derived server-side from the reservation, never your request, and the buyer's signature is verified before any capture. A per-buyer refusal (FORBIDDEN, cap-exceeded, FULFILLMENT_REQUIRED) returns as an error result; a missing or invalid identity is a real 401. REQUIRES IDENTITY plus a signed Idempotency-Key on a signature-required Terminal.

Argument	Type	Description
payment*	object	The payment container `{ instruments: [{ credential: { type, ... } }] }`, where credential.type is `x402_authorization` or `boson_commit_authorization`. Sign the seller-signed offer LOCALLY with your own wallet; Facet never holds your key.
checkout_id*	string	The checkout id from create_checkout.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "checkout_id",
    "payment"
  ],
  "properties": {
    "payment": {
      "type": "object",
      "description": "The payment container `{ instruments: [{ credential: { type, ... } }] }`, where credential.type is `x402_authorization` or `boson_commit_authorization`. Sign the seller-signed offer LOCALLY with your own wallet; Facet never holds your key."
    },
    "checkout_id": {
      "type": "string",
      "description": "The checkout id from create_checkout."
    }
  }
}

create_cart

Create a pre-checkout cart from catalog line items. A cart is a mutable scratchpad: it moves no money and holds no inventory, so it carries estimated (server-derived) totals and NO payment_handlers. Assemble it, then create_checkout(cart_id) to convert. REQUIRES IDENTITY on a signature-required Terminal.

Argument	Type	Description
line_items	array	Items, each `{ item: { id }, quantity }`. Prices are catalog-derived, never yours.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "line_items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item": {
            "type": "object",
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string"
              }
            }
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "description": "Items, each `{ item: { id }, quantity }`. Prices are catalog-derived, never yours."
    }
  }
}

create_checkout

Open a checkout session for one or more catalog line items (or promote a cart with `cart_id`). Returns the session plus server-resolved `payment_handlers` (rail, pay_to, exact amount) to satisfy: the price and pay_to are the MERCHANT's, sealed here, never read from your request. Physical goods REQUIRE a `fulfillment` ship-to (else FULFILLMENT_REQUIRED), sealed at create. REQUIRES IDENTITY on a signature-required Terminal: a Facet KYA as `Authorization: Bearer <kya>`.

Argument	Type	Description
cart_id	string	Promote an existing cart: its stored lines drive the checkout and any line_items are ignored (the business must use the cart contents).
line_items	array	Items to buy, each `{ item: { id }, quantity }`. Omit when using cart_id.
fulfillment	object	Ship-to destination. REQUIRED for physical products; sealed at create.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "cart_id": {
      "type": "string",
      "description": "Promote an existing cart: its stored lines drive the checkout and any line_items are ignored (the business must use the cart contents)."
    },
    "line_items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item": {
            "type": "object",
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string"
              }
            }
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "description": "Items to buy, each `{ item: { id }, quantity }`. Omit when using cart_id."
    },
    "fulfillment": {
      "type": "object",
      "description": "Ship-to destination. REQUIRED for physical products; sealed at create."
    }
  }
}

discover_businesses

Find businesses in the Facet Universal Business Index that an agent can transact with. Returns `featured` (claimed merchants with a live `terminal_url` — point your catalog and checkout calls there) and `results` (the wider directory). Use this first when you do not already know which merchant to talk to. REQUIRES IDENTITY: send a Facet KYA as `Authorization: Bearer <kya>` on the MCP request. A KYA is an ES256 JWT from Facet's default issuer https://issuer.facet.llc (or another issuer this Terminal trusts — see KYA-Issuers in its /.well-known/agents.txt). Calling without one returns 401 with a signup link.

Argument	Type	Description
near	object	Optional geographic center to rank by proximity.
limit	integer	Max matches to return. Default 10, cap 50.
query	string	Free-text query, e.g. "flowers" or "makeup brushes".
radius_km	number	Search radius around `near`, km. Default 25.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "near": {
      "type": "object",
      "required": [
        "lat",
        "lng"
      ],
      "properties": {
        "lat": {
          "type": "number",
          "description": "Latitude, decimal degrees."
        },
        "lng": {
          "type": "number",
          "description": "Longitude, decimal degrees."
        }
      },
      "description": "Optional geographic center to rank by proximity."
    },
    "limit": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Max matches to return. Default 10, cap 50."
    },
    "query": {
      "type": "string",
      "description": "Free-text query, e.g. \"flowers\" or \"makeup brushes\"."
    },
    "radius_km": {
      "type": "number",
      "description": "Search radius around `near`, km. Default 25."
    }
  }
}

discover_products

Search products ACROSS every merchant in the Facet network that has opted into cross-merchant discovery. Returns matches each carrying the selling merchant's `terminal_url` (point your catalog and checkout calls there). Filter by free-text `query` (product name + description), exact `category`, and/or `tags` (all must be present); at least one filter is required. Use this when you know WHAT you want but not WHICH merchant sells it. REQUIRES IDENTITY: send a Facet KYA as `Authorization: Bearer <kya>` on the MCP request. A KYA is an ES256 JWT from Facet's default issuer https://issuer.facet.llc (or another issuer this Terminal trusts; see KYA-Issuers in its /.well-known/agents.txt). Calling without one returns 401 with a signup link.

Argument	Type	Description
tags	array	Tags that must ALL be present on a matching product.
limit	integer	Max matches to return. Default 10, cap 50.
query	string	Free-text over product name + description, e.g. "lavender soap".
category	string	Exact product category to match.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tags that must ALL be present on a matching product."
    },
    "limit": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Max matches to return. Default 10, cap 50."
    },
    "query": {
      "type": "string",
      "description": "Free-text over product name + description, e.g. \"lavender soap\"."
    },
    "category": {
      "type": "string",
      "description": "Exact product category to match."
    }
  }
}

get_cart

Read back one of YOUR carts by id: line items and estimated totals. Owner-scoped, so another agent's id returns not_found. REQUIRES IDENTITY on a signature-required Terminal.

Argument	Type	Description
id*	string	The cart id.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The cart id."
    }
  }
}

get_checkout

Read back one of YOUR checkout sessions by id: status, totals, line items, payment_handlers. Owner-scoped, so another agent's id returns not_found. REQUIRES IDENTITY on a signature-required Terminal.

Argument	Type	Description
id*	string	The checkout session id.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The checkout session id."
    }
  }
}

get_order

Read back one of YOUR orders on this merchant: status, amount, settlement state. Use the order_id returned when you paid. You can only read orders your own agent identity placed — another agent's order returns FORBIDDEN. REQUIRES IDENTITY: Facet KYA as `Authorization: Bearer <kya>`.

Argument	Type	Description
order_id*	string	The order id returned at payment.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "order_id"
  ],
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order id returned at payment."
    }
  }
}

get_payment_capabilities

Which settlement rails this merchant actually accepts (e.g. coin/boson-escrow for escrowed funds that release on fulfilment, coin/usdc-base for direct). Call before get_payment_requirements so you pass a rail_id this merchant registers, rather than guessing. No identity required — this is discovery data.

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

get_payment_requirements

Turn a `quote_token` from get_quote into a seller-signed payment offer to authorize. Returns `requirements` (escrow address, asset, exact atomic amount, network) — sign it LOCALLY with your own wallet (e.g. @bosonprotocol/x402-client handle402 for `coin/boson-escrow`, producing an X-PAYMENT string). Facet never holds your key and cannot sign for you, which is why paying is two steps and not one. The offer binds to the quote_token's sealed landed total and ship-to, so the amount is the merchant's, not one you name. REQUIRES IDENTITY: same Facet KYA as get_quote, and the SAME `aid` — the offer path rejects a quote_token issued to a different agent than the caller.

Argument	Type	Description
qty	integer	Must match the quote_token. Default 1.
amount*	object	The landed total in ATOMIC units. Must equal the quote_token's sealed total.
rail_id*	string	Settlement rail, e.g. "coin/boson-escrow" (escrow: funds release on fulfilment) or "coin/usdc-base". See /v1/payments/capabilities for what this merchant registers.
site_id	string	Usually omitted — this Terminal's bound site is used.
product_id*	string	Must match the product the quote_token sealed.
quote_token*	string	The signed token from get_quote.

get_product

Get full product detail by product or variant identifier.

Argument	Type	Description
catalog*	object

Input schema (JSON)

{
  "type": "object",
  "required": [
    "catalog"
  ],
  "properties": {
    "catalog": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "string"
        }
      }
    }
  }
}

get_quote

Get the real landed cost of a product from this merchant: goods + shipping + tax for a specific destination, plus a signed `quote_token` the payment path binds to. Call this before paying — the token is what makes the price the MERCHANT's, not one you name. Physical products REQUIRE a `fulfillment` ship-to; without one you get FULFILLMENT_REQUIRED. An unserviceable destination returns UNDELIVERABLE (the merchant's own shipping zones, which Facet cannot waive). REQUIRES IDENTITY: send a Facet KYA as `Authorization: Bearer <kya>` (ES256 JWT from https://issuer.facet.llc, or another issuer in this Terminal's agents.txt KYA-Issuers).

Argument	Type	Description
qty	integer	Quantity. Default 1.
site_id	string	Usually omitted — this Terminal's bound site is used.
product_id*	string	Product or variant id, e.g. from search_catalog.
fulfillment	object	Ship-to destination. REQUIRED for physical products.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "product_id"
  ],
  "properties": {
    "qty": {
      "type": "integer",
      "minimum": 1,
      "description": "Quantity. Default 1."
    },
    "site_id": {
      "type": "string",
      "description": "Usually omitted — this Terminal's bound site is used."
    },
    "product_id": {
      "type": "string",
      "description": "Product or variant id, e.g. from search_catalog."
    },
    "fulfillment": {
      "type": "object",
      "properties": {
        "mode": {
          "enum": [
            "inline",
            "ref"
          ],
          "type": "string",
          "description": "`inline` with a full address, or `ref` to reuse a prior fulfillment_ref."
        },
        "address": {
          "type": "object",
          "required": [
            "recipient",
            "line1",
            "locality",
            "region",
            "postal_code",
            "country"
          ],
          "properties": {
            "line1": {
              "type": "string"
            },
            "line2": {
              "type": "string"
            },
            "phone": {
              "type": "string"
            },
            "region": {
              "type": "string",
              "description": "State/province. Required even where the country has none."
            },
            "country": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2, e.g. US."
            },
            "locality": {
              "type": "string",
              "description": "City."
            },
            "recipient": {
              "type": "string"
            },
            "postal_code": {
              "type": "string"
            }
          },
          "description": "All six fields are required, including `region`."
        },
        "fulfillment_ref": {
          "type": "string",
          "description": "Opaque ref from a prior quote (mode `ref`)."
        }
      },
      "description": "Ship-to destination. REQUIRED for physical products."
    }
  }
}

list_orders

List YOUR order history on this merchant, newest first. Scoped to your own agent identity — you never see another agent's orders. REQUIRES IDENTITY: Facet KYA as `Authorization: Bearer <kya>`.

Argument	Type	Description
limit	integer	Max orders to return.
cursor	string	Opaque cursor from a previous page.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "description": "Max orders to return."
    },
    "cursor": {
      "type": "string",
      "description": "Opaque cursor from a previous page."
    }
  }
}

lookup_catalog

Look up one or more products or variants by identifier (batch).

Argument	Type	Description
catalog*	object

Input schema (JSON)

{
  "type": "object",
  "required": [
    "catalog"
  ],
  "properties": {
    "catalog": {
      "type": "object",
      "required": [
        "ids"
      ],
      "properties": {
        "ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 100,
          "minItems": 1
        }
      }
    }
  }
}

post_delivery_refund

Request a refund or return on a DELIVERED order you placed on this merchant. Opens a merchant-approved refund ticket (status `requested`); it moves NO money on its own. The merchant reviews and approves it, and only then does the send-back sign from the merchant's OWN wallet (non-custodial). Amount and recipient are NOT inputs: the refund amount is derived and capped server-side, and the recipient is the order's stamped payer, never one you name. Pass `refund_line_items` to refund only part of the order; omit for the whole order. Owner-scoped: another agent's order returns FORBIDDEN. REQUIRES IDENTITY: a Facet KYA as `Authorization: Bearer <kya>` (an ES256 JWT from https://issuer.facet.llc, or another issuer in this Terminal's agents.txt KYA-Issuers). A wallet-bound KYA also authorizes a platform-originated order by its stamped payer.

Argument	Type	Description
reason*	string	Why the refund or return is requested. Required.
receipt	object	Optional Ed25519-signed settlement receipt (the signed settle response you received). When valid and bound to this order it records receipt_verified on the ticket; it never gates the refund.
order_id*	string	The order id returned at payment (settle / checkout complete). A reservation id is not an order id.
refund_line_items	array	Optional PARTIAL selection: refund only these lines instead of the whole order. Advisory at request time; the merchant is authoritative and may adjust it at decide. Omit for a full-order refund.

Input schema (JSON)

search_catalog

Search the merchant catalog for products matching a free-text query.

Argument	Type	Description
catalog*	object

Input schema (JSON)

{
  "type": "object",
  "required": [
    "catalog"
  ],
  "properties": {
    "catalog": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "Free-text search query."
        },
        "pagination": {
          "type": "object",
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1
            },
            "cursor": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

update_cart

Replace a cart's line items (full replacement), re-priced server-side. Owner-scoped. REQUIRES IDENTITY on a signature-required Terminal.

Argument	Type	Description
id*	string	The cart id.
line_items	array	The new full set of items, each `{ item: { id }, quantity }`.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The cart id."
    },
    "line_items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item": {
            "type": "object",
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string"
              }
            }
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "description": "The new full set of items, each `{ item: { id }, quantity }`."
    }
  }
}

update_checkout

Return a checkout's CURRENT sealed snapshot. Facet seals price and items at create, so this is a no-op that reports the session plus a note: to change line items, update the cart and start a new checkout with create_checkout(cart_id). Owner-scoped.

Argument	Type	Description
id*	string	The checkout session id.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The checkout session id."
    }
  }
}

wishlist_add

Save a product to YOUR wishlist on this merchant for later. Idempotent: saving the same product again updates its note and keeps the original save time. Scoped to your own agent identity. REQUIRES IDENTITY: Facet KYA as `Authorization: Bearer <kya>`.

Argument	Type	Description
note	string	Optional short note. No personal data.
product_id*	string	The product id to save.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "product_id"
  ],
  "properties": {
    "note": {
      "type": "string",
      "description": "Optional short note. No personal data."
    },
    "product_id": {
      "type": "string",
      "description": "The product id to save."
    }
  }
}

wishlist_list

List YOUR saved items (wishlist) on this merchant, newest first. Scoped to your own agent identity, so you never see another agent's list. REQUIRES IDENTITY: Facet KYA as `Authorization: Bearer <kya>`.

Argument	Type	Description
limit	integer	Max items to return.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "description": "Max items to return."
    }
  }
}

wishlist_remove

Remove a product from YOUR wishlist on this merchant. Idempotent: removing something not on your list succeeds with removed:false. Scoped to your own agent identity. REQUIRES IDENTITY: Facet KYA as `Authorization: Bearer <kya>`.

Argument	Type	Description
product_id*	string	The product id to remove.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "product_id"
  ],
  "properties": {
    "product_id": {
      "type": "string",
      "description": "The product id to remove."
    }
  }
}

{
  "type": "object",
  "required": [
    "product_id",
    "rail_id",
    "amount",
    "quote_token"
  ],
  "properties": {
    "qty": {
      "type": "integer",
      "minimum": 1,
      "description": "Must match the quote_token. Default 1."
    },
    "amount": {
      "type": "object",
      "required": [
        "amount",
        "currency"
      ],
      "properties": {
        "amount": {
          "type": "integer",
          "description": "Atomic units, e.g. 16930000 for $16.93 USDC (6dp)."
        },
        "currency": {
          "type": "string",
          "description": "e.g. \"USDC\"."
        }
      },
      "description": "The landed total in ATOMIC units. Must equal the quote_token's sealed total."
    },
    "rail_id": {
      "type": "string",
      "description": "Settlement rail, e.g. \"coin/boson-escrow\" (escrow: funds release on fulfilment) or \"coin/usdc-base\". See /v1/payments/capabilities for what this merchant registers."
    },
    "site_id": {
      "type": "string",
      "description": "Usually omitted — this Terminal's bound site is used."
    },
    "product_id": {
      "type": "string",
      "description": "Must match the product the quote_token sealed."
    },
    "quote_token": {
      "type": "string",
      "description": "The signed token from get_quote."
    }
  }
}

{
  "type": "object",
  "required": [
    "order_id",
    "reason"
  ],
  "properties": {
    "reason": {
      "type": "string",
      "description": "Why the refund or return is requested. Required."
    },
    "receipt": {
      "type": "object",
      "properties": {
        "body": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "trace_id": {
          "type": "string"
        },
        "signature": {
          "type": "string"
        }
      },
      "description": "Optional Ed25519-signed settlement receipt (the signed settle response you received). When valid and bound to this order it records receipt_verified on the ticket; it never gates the refund."
    },
    "order_id": {
      "type": "string",
      "description": "The order id returned at payment (settle / checkout complete). A reservation id is not an order id."
    },
    "refund_line_items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "product_id",
          "qty"
        ],
        "properties": {
          "qty": {
            "type": "integer",
            "minimum": 1,
            "description": "At most the ordered quantity for that line."
          },
          "product_id": {
            "type": "string",
            "description": "A product id present in the order."
          }
        }
      },
      "description": "Optional PARTIAL selection: refund only these lines instead of the whole order. Advisory at request time; the merchant is authoritative and may adjust it at decide. Omit for a full-order refund."
    }
  }
}