search_catalog

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

Parameters1

catalog

object

required

Raw schema

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

lookup_catalog

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

Parameters1

catalog

object

required

Raw schema

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

get_product

Get full product detail by product or variant identifier.

Parameters1

catalog

object

required

Raw schema

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

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.

Parameters4

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

Raw schema

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

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).

Parameters4

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

Raw schema

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

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.

Parameters

No parameters.

Raw schema

{
  "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.

Parameters6

product_id	string	required	Must match the product the quote_token sealed.
qty	integer	optional	Must match the quote_token. Default 1.
rail_id	string	required	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.
amount	object	required	The landed total in ATOMIC units. Must equal the quote_token's sealed total.
quote_token	string	required	The signed token from get_quote.
site_id	string	optional	Usually omitted — this Terminal's bound site is used.

Raw schema

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "Must match the product the quote_token sealed."
    },
    "qty": {
      "type": "integer",
      "minimum": 1,
      "description": "Must match the quote_token. Default 1."
    },
    "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."
    },
    "amount": {
      "type": "object",
      "required": [
        "amount",
        "currency"
      ],
      "description": "The landed total in ATOMIC units. Must equal the quote_token's sealed total.",
      "properties": {
        "amount": {
          "type": "integer",
          "description": "Atomic units, e.g. 16930000 for $16.93 USDC (6dp)."
        },
        "currency": {
          "type": "string",
          "description": "e.g. \"USDC\"."
        }
      }
    },
    "quote_token": {
      "type": "string",
      "description": "The signed token from get_quote."
    },
    "site_id": {
      "type": "string",
      "description": "Usually omitted — this Terminal's bound site is used."
    }
  },
  "required": [
    "product_id",
    "rail_id",
    "amount",
    "quote_token"
  ]
}

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>`.

Parameters1

order_id

string

required

The order id returned at payment.

Raw schema

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

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>`.

Parameters2

limit	integer	optional	Max orders to return.
cursor	string	optional	Opaque cursor from a previous page.

Raw schema

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

Facet UCP Shopping

MCP Server: llc.facet/ucp-shopping

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

search_catalog

lookup_catalog

get_product

discover_businesses

get_quote

get_payment_capabilities

get_payment_requirements

get_order

list_orders

Install

Remote endpoint