MCP-Server
Facet UCP Shopping
llc.facet/ucp-shopping
Was dieses MCP kann
Discovers products and merchants, manages carts and checkout sessions, and supports agent-mediated purchases, orders, and refunds.
Funktionen
Tools
23
Tools
cancel_cart
Cancel a cart. Idempotent, owner-scoped, and moves no money. REQUIRES IDENTITY plus an Idempotency-Key on a signature-required Terminal.
Eingabeschema
{'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.
Eingabeschema
{'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.
Eingabeschema
{'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.
Eingabeschema
{'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>`.
Eingabeschema
{'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.
Eingabeschema
{'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.
Eingabeschema
{'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.
Eingabeschema
{'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.
Eingabeschema
{'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>`.
Eingabeschema
{'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.
Eingabeschema
{'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.
Eingabeschema
{'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.'}}}
get_product
Get full product detail by product or variant identifier.
Eingabeschema
{'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).
Eingabeschema
{'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>`.
Eingabeschema
{'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).
Eingabeschema
{'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.
Eingabeschema
{'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.'}}}
search_catalog
Search the merchant catalog for products matching a free-text query.
Eingabeschema
{'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.
Eingabeschema
{'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.
Eingabeschema
{'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>`.
Eingabeschema
{'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>`.
Eingabeschema
{'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>`.
Eingabeschema
{'type': 'object', 'required': ['product_id'], 'properties': {'product_id': {'type': 'string', 'description': 'The product id to remove.'}}}
Verlauf
Letzte Tool-Änderungen
Hinzugefügt
cancel_cart
17. September 2026 12:54
Hinzugefügt
update_cart
17. September 2026 12:54
Hinzugefügt
get_cart
17. September 2026 12:54
Hinzugefügt
create_cart
17. September 2026 12:54
Hinzugefügt
cancel_checkout
17. September 2026 12:54
Hinzugefügt
update_checkout
17. September 2026 12:54
Hinzugefügt
get_checkout
17. September 2026 12:54
Hinzugefügt
complete_checkout
17. September 2026 12:54
Hinzugefügt
create_checkout
17. September 2026 12:54
Hinzugefügt
wishlist_remove
17. September 2026 12:54
Hinzugefügt
wishlist_list
17. September 2026 12:54
Hinzugefügt
wishlist_add
17. September 2026 12:54
Hinzugefügt
post_delivery_refund
17. September 2026 12:54
Hinzugefügt
list_orders
17. September 2026 12:54
Hinzugefügt
get_order
17. September 2026 12:54
Hinzugefügt
get_payment_requirements
17. September 2026 12:54
Hinzugefügt
get_payment_capabilities
17. September 2026 12:54
Hinzugefügt
get_quote
17. September 2026 12:54
Hinzugefügt
discover_products
17. September 2026 12:54
Hinzugefügt
discover_businesses
17. September 2026 12:54
Hinzugefügt
get_product
17. September 2026 12:54
Hinzugefügt
lookup_catalog
17. September 2026 12:54
Hinzugefügt
search_catalog
17. September 2026 12:54
Entdecken
Ähnliche MCP-Server
AgentLot Marketplace
io.agentlot/marketplace
Enables agents and users to discover, bid on, purchase, deliver, and settle paid digital services and compute work.
Digital Manager Guru
io.github.mcp-dir/guru-mcp
Provides Digital Manager Guru checkout, customer, transaction, subscription, affiliate, coupon, blocklist, and digital-product sa…
Pagar.me
io.github.mcp-dir/pagarme-mcp
Connects to Pagar.me to manage customers, cards, orders, charges, invoices, payment captures, confirmations, retries, refunds, an…
roastify-mcp
io.github.lonniev/roastify-mcp
Supports a coffee commerce workflow with product and blend catalogs, inventory, coupons, packaging design editing, artwork genera…
bitroad
ai.bitroad/bitroad
Enables agents to search and purchase marketplace goods under spending controls, manage orders and returns, and handle payments a…
Singularity Layer MCP
io.github.ivaavimusic/singularity
Provides marketplace discovery, agent endpoint and asset management, dataset and product purchases, payment flows, and ERC-8004 a…
agentic-commerce
io.bosonprotocol/agentic-commerce
Enables on-chain commerce through Boson Protocol, including product offers, buyer and seller accounts, voucher exchanges, escrow-…
agentcard
sh.agentcard/agentcard
Manages prepaid virtual cards with spending controls, approvals, funding, rewards, and connected-merchant shopping flows.