Multi-seller shopping for AI agents. Settle via Stripe MPP or x402 USDC on Base. Hosted.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Bearer <kfa_live_...> — agent API key issued from the Kifly seller portal at https://kifly.io/dashboard/api-keys. One key per seller (or per cross-seller network) determines catalog scope.
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.
Requires `cart:write`, or no key: send `meta.ucp-agent.profile`. Add a product variant to an existing cart. Use the variant_id from search_products results. Returns full cart state including item_ids you can use with update_cart_item. **Max quantity per item and max cart total are enforced — call `get_platform_limits` to check the current limits before building a large cart.** Exceeding the per-item limit returns 400 `QUANTITY_EXCEEDS_LIMIT`; exceeding the cart total returns 400 `CART_TOTAL_EXCEEDS_LIMIT` at checkout. `cart.kifly_purchasable` (and `cart.fulfillment`) carries the same signal as create_cart's `seller` field.
Cart ID from create_cart
Product variant ID from search_products results
Who is calling. See kifly://docs/mcp.
Quantity to add
Your own retry key (16-64 chars). Resend the SAME key to retry safely.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Requires `cart:write`, or no key: send `meta.ucp-agent.profile`. Add a product variant to an existing cart. Use the variant_id from search_products results. Returns full cart state including item_ids you can use with update_cart_item. **Max quantity per item and max cart total are enforced — call `get_platform_limits` to check the current limits before building a large cart.** Exceeding the per-item limit returns 400 `QUANTITY_EXCEEDS_LIMIT`; exceeding the cart total returns 400 `CART_TOTAL_EXCEEDS_LIMIT` at checkout. `cart.kifly_purchasable` (and `cart.fulfillment`) carries the same signal as create_cart's `seller` field.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
| cart_id* | string | Cart ID from create_cart |
| quantity | integer | Quantity to add |
| variant_id* | string | Product variant ID from search_products results |
| idempotency_key | string | Your own retry key (16-64 chars). Resend the SAME key to retry safely. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id",
"variant_id"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
},
"cart_id": {
"type": "string",
"description": "Cart ID from create_cart"
},
"quantity": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Quantity to add"
},
"variant_id": {
"type": "string",
"description": "Product variant ID from search_products results"
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
}
},
"additionalProperties": false
}Requires `checkout:write` or `checkout:link`, or no key: send `meta.ucp-agent.profile` for the same payment link. **Checkout is always human-in-the-loop: it returns a link the buyer opens and confirms — it never charges a card or completes an order on its own.** **Call `set_shipping_address` first unless `fulfillment` is `"external"` (the seller's site collects the address).** Cart total must not exceed the platform cap (`kifly://platform/limits`). **To pre-fill the buyer's email on the payment page, pass `email` — ask the buyer for it in plain language ('what email should the receipt go to?'). Never ask the buyer to paste a token.** Read `payment_rail` on the response BEFORE telling the buyer anything: `'stripe-checkout'` is paid through Kifly, `'directory-handoff'` hands the buyer to the seller's own site to pay, with a tracked link per product and no Kifly payment link, and `'shopify-native'` sends the buyer to the seller's own checkout. **Full response field reference, including every refusal code: read the `kifly://docs/checkout-response` resource.**
| Argument | Type | Description |
|---|---|---|
| string | Buyer's email, collected conversationally. Pre-fills the Stripe Checkout email field so the buyer doesn't retype it. This is ALL you need to pre-fill email — ask the buyer for their email, never for a token. | |
| cart_id* | string | Cart ID from create_cart |
| buyer_token | string | INTERNAL token (kfb_live_...) minted by register_buyer / verify_buyer — resolves the buyer's saved profile and pre-fills their email on the payment link. NEVER ask the buyer to paste this. Omit it unless you already obtained one programmatically this session; to pre-fill email, use `email` instead. |
Create a new shopping cart on Kifly. **For network (cross-seller) tokens you MUST pass `seller_handle`** — each cart is bound to exactly one seller. Get the handle from search_products results (every item's `kifly:seller` IS the handle in network results) or get_seller. Seller-scoped tokens may omit the handle — their own seller is implicit. Returns a cart_id to use with add_to_cart and checkout. The response's `seller.kifly_purchasable` (and `seller.fulfillment`) tells you upfront where the buyer pays — `false`/`"external"` means the buyer pays on the seller's own site: build the cart as usual; checkout hands them there with a link per product. Never say the order is placed. The same flag rides every add_to_cart/get_cart response.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
| seller_handle | string | Seller handle (e.g. 'bay-clothing-district'). Required for network tokens; ignored for seller-scoped tokens. |
| idempotency_key | string | Your own retry key (16-64 chars). Resend the SAME key to retry safely. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
},
"seller_handle": {
"type": "string",
"description": "Seller handle (e.g. 'bay-clothing-district'). Required for network tokens; ignored for seller-scoped tokens."
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
}
},
"additionalProperties": false
}Retrieve a repeat buyer's saved name, email, and default shipping address, given their `buyer_token`. Use them to auto-fill `set_shipping_address`, and pass the token to `checkout` so Stripe pre-fills their email. `default_shipping_address` may be null — then collect it normally and call `save_buyer_address` so it is pre-filled next time. **Ask in plain language ('are you a returning Kifly shopper? what email is on your account?') — never ask a buyer to paste a token.** **How to get the token: read `kifly://docs/buyer-identity`** — the email-code sequence, the one-click sign-in alternative, and what to do for a new buyer.
| Argument | Type | Description |
|---|---|---|
| buyer_token* | string | The buyer's kfb_live_... token from their Kifly account |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"buyer_token"
],
"properties": {
"buyer_token": {
"type": "string",
"minLength": 1,
"description": "The buyer's kfb_live_... token from their Kifly account"
}
},
"additionalProperties": false
}Inspect the current state of a cart — line items, quantities, prices, and shipping address. Each item includes an `item_id` you can pass to `update_cart_item` to change quantity or remove the item. Call this after `add_to_cart` to review the cart before checkout, or any time the buyer asks what's in the cart. `kifly_purchasable: false` (`fulfillment: "external"`) means checkout on this cart hands the buyer to the seller's own site to pay: say so, so the buyer knows where they will pay.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
| cart_id* | string | Cart ID from create_cart |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
},
"cart_id": {
"type": "string",
"description": "Cart ID from create_cart"
}
},
"additionalProperties": false
}Get unstuck. Returns Kifly's website and support email for the BUYER, plus how to report the problem to Kifly's engineers yourself. Call this if you are stuck, hit an unresolvable error, or the buyer asks how to reach a human. Share the website and email with the buyer; use `submit_feedback` (no API key needed) to tell us what blocked you — that is the fastest way to get it fixed.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
}
},
"additionalProperties": false
}Returns the current platform-enforced cart limits: `max_item_quantity` (per-line-item ceiling), `max_cart_total_cents`, and `max_cart_total_usd`. Call this once at session start before building a large cart so you can quote limits to the buyer proactively rather than discovering them via errors. Always read them at runtime rather than hardcoding.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
}
},
"additionalProperties": false
}The seller's published returns, shipping and warranty policy, in their own words. **Call before telling a buyer what happens after purchase** — if it is not here, say so; never infer a typical policy. `available: false` is the normal case for most sellers and is not an error. `get_seller`'s `policies.available` tells you whether this call is worth making. Network tokens pass `handle`; seller-scoped tokens may omit it.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
| handle | string | Seller handle (case-insensitive). Required for network tokens; ignored for seller-scoped tokens. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
},
"handle": {
"type": "string",
"description": "Seller handle (case-insensitive). Required for network tokens; ignored for seller-scoped tokens."
}
},
"additionalProperties": false
}**Call first when the user names a store or its website**: it says whether Kifly carries it before you open a browser. Returns the seller's public profile: location, storefront URL, delivery fee and coverage, catalog size, `verified_domains` (domains it proved it controls; trust signal, not identity), and `fulfillment` (buy here, or hand off to the seller's site). **Call before `create_cart` or `set_shipping_address` to check it ships to the buyer.** `cities` is never capped here. **`coverage_configured: false` = ships NOWHERE; an empty `states` is NOT nationwide. `merchant_managed: true` = shipping is set at the seller's own checkout; never report it as not shipping.** Details: `kifly://docs/delivery`. Name the seller by ONE of `handle`, `domain` (any URL works) or `name`. A miss is `SELLER_NOT_FOUND` with `details.did_you_mean`: ask the user, never pick. `SELLER_AMBIGUOUS` = several share that name; ask which. Seller-scoped tokens may omit all three.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
| name | string | The store's name. |
| domain | string | The store's website or any URL on it. |
| handle | string | Seller handle, case-insensitive (e.g. 'bay-clothing-district'). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
},
"name": {
"type": "string",
"maxLength": 200,
"description": "The store's name."
},
"domain": {
"type": "string",
"maxLength": 2048,
"description": "The store's website or any URL on it."
},
"handle": {
"type": "string",
"description": "Seller handle, case-insensitive (e.g. 'bay-clothing-district')."
}
},
"additionalProperties": false
}List a returning buyer's recent orders and their current fulfillment status — use this in a NEW session to answer 'did my order ship?' / 'where's my package?' when you don't have the original `session_id` from `checkout`. Requires the buyer's `buyer_token` (recover it via `request_buyer_code` + `verify_buyer` if you don't have one). Returns `{ orders, count }`, newest first; each order has `status` (`paid` | `shipped` | `delivered`), `items`, `amount_cents`, `placed_at`, and — once shipped — `tracking_number`, `carrier`, and a public `tracking_url`. **Pass `since` (an ISO-8601 timestamp from a previous check) to get only orders that changed since then** — surface those proactively ('your last order just shipped'). `order_id` identifies the order; `session_id` cross-references `order_status` for a single live checkout.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Max orders to return (default 20, max 50). |
| since | string | ISO-8601 timestamp. Only return orders updated after this — pass the time of your last check to get the delta. |
| buyer_token* | string | The buyer's kfb_live_... token from their Kifly account |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"buyer_token"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Max orders to return (default 20, max 50)."
},
"since": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp. Only return orders updated after this — pass the time of your last check to get the delta."
},
"buyer_token": {
"type": "string",
"minLength": 1,
"description": "The buyer's kfb_live_... token from their Kifly account"
}
},
"additionalProperties": false
}List all active sellers on the Kifly network. **Requires a network token (kfn_live_…).** Returns each seller's handle, name, city, region, delivery coverage (`nationwide:true` or a `states` list), delivery fee, and catalog size. `delivery_coverage.cities` may be capped to a handful of entries — compare `cities.length` against `city_count`; if fewer, call `get_seller` for that seller's full city list. Use this to discover which sellers are available and which ship to a buyer's location before calling `get_seller` or `search_products`. **Pagination:** when `kifly:hasMore` is true, pass `kifly:nextCursor` as `cursor` to fetch the next page. Default page size is 20, max 50.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
| limit | integer | Max sellers per page (default 20, max 50). |
| cursor | string | Pagination cursor from kifly:nextCursor in a previous response. Omit on the first call. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
},
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Max sellers per page (default 20, max 50)."
},
"cursor": {
"type": "string",
"description": "Pagination cursor from kifly:nextCursor in a previous response. Omit on the first call."
}
},
"additionalProperties": false
}No key needed for your own session: send the profile you checked out with. Check the status of a Stripe checkout session. Poll every 5 seconds after checkout until status is 'paid', 'shipped', or 'failed'. Returns order details (order_id, amount, items) when paid. When the seller marks the order as shipped, status becomes 'shipped' and tracking_number, carrier, and shipped_at are included — share these with the buyer.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Stripe checkout session ID from the checkout tool response |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Stripe checkout session ID from the checkout tool response"
}
},
"additionalProperties": false
}Requires `cart:write` scope. Create a cart, add items, and set the shipping address in ONE call — the fast path when you already know the seller, the exact variant(s), and the buyer's address (e.g. a reorder, or a buyer who has decided). Prefer this over the create_cart → add_to_cart → set_shipping_address sequence to save round trips; those granular tools stay available for exploratory, multi-step carts. **You must call `search_products` first** so Kifly knows each variant's seller (quick_buy returns 422 `VARIANT_SNAPSHOT_MISSING` otherwise). One cart = one seller: every item must belong to the same seller (409 `CART_SELLER_MISMATCH` otherwise) — for a network token, pass that seller's `seller_handle`. Returns `{ cart_id, items_added, seller, delivery }`. `delivery` is exactly what `set_shipping_address` returns — **quote `cart_total_with_delivery_cents` before sending the buyer to pay**; on `delivery_eligible: false` no address is saved, so you can call again with a covered address. Field detail and the three coverage cases: `kifly://docs/delivery`. **quick_buy never charges — it stops at the cart. The buyer still pays via `checkout`**, which returns the payment link they open themselves. On a 5xx/'temporarily unavailable' error, retry once with the same arguments.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
| items* | array | Line items to add — all must belong to the same seller |
| seller_handle | string | Seller handle from search_products. REQUIRED for network tokens; omit for seller-scoped tokens (their own seller is implicit). |
| idempotency_key | string | Your own retry key (16-64 chars). Resend the SAME key to retry safely. |
Start registering a buyer so they can be recognized across future purchases without re-entering their details. Takes the buyer's email and name and always emails a 6-digit verification code — the response is `{ verification_required: true, buyer_profile_id }` whether the email is brand new or already has an account (so this call alone never reveals which). Ask the buyer to read you the code from their inbox, then call `verify_buyer` with the same email + code to get a `buyer_token` (`kfb_live_...`). **Store that token and pass it to `checkout` on every future order** — it pre-fills the buyer's email on the secure Stripe payment link. Safe to call for a buyer you believe is new; if they already have an account, verify_buyer still recovers it.
| Argument | Type | Description |
|---|---|---|
| name* | string | Buyer's full name |
| email* | string | Buyer's email address |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email",
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Buyer's full name"
},
"email": {
"type": "string",
"format": "email",
"description": "Buyer's email address"
}
},
"additionalProperties": false
}Send a 6-digit verification code to a **returning** buyer's email so they can prove the account is theirs and recover their saved name + shipping address on this connection — without pasting any token or re-entering their name. Call this when the buyer says they've shopped with Kifly before and gives you their email; then ask them to read you the code from their inbox and call `verify_buyer`. Always returns `{ sent: true }`, whether or not the email has a Kifly account. If the buyer never receives a code, they likely don't have an account yet: call `register_buyer` instead, which creates one and emails a code either way. Requires the `buyer:write` capability (marketplace/network keys).
| Argument | Type | Description |
|---|---|---|
| email* | string | The returning buyer's email address |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "The returning buyer's email address"
}
},
"additionalProperties": false
}Submit the buyer's **product/feature request** to the Kifly team. Use this when the buyer wishes Kifly *itself* did something it doesn't — a missing capability, a rough flow, an idea to improve the platform. **This is NOT `submit_feedback`** (that's for reporting a broken/confusing API response you hit). Requires the buyer's `kfb_live_` token — only registered buyers can file requests. Help the buyer articulate a real problem: ask OPEN, non-leading questions ('what were you trying to do? what got in the way? how do you handle it today?') — never 'would feature X help?'. Pre-fill the fields from the conversation and ask only for the gaps; keep it short. Separate the `problem` (the pain) from any `proposed_solution` (the fix). Name and email are taken from the buyer profile automatically — do not ask for them. Returns 202: it's logged for review. **Do NOT promise the user anything will be built** — just confirm it was recorded.
| Argument | Type | Description |
|---|---|---|
| impact* | string | Why it matters: who it affects, how often, what it costs them today. |
| context | object | Optional signal about the conversation: { goal, seller, last_tool }. Auto-fill from what you were doing. |
| problem* | string | The pain in the buyer's own terms — what's broken or missing for them. NOT the proposed fix. |
| category* | string | Closest match for the area of the request. Don't invent new categories. |
| severity* | string | blocker = can't accomplish the goal at all. friction = works but painful. nice_to_have = improvement idea. |
Save a shipping address to the buyer's Kifly profile so it auto-fills on future purchases. **Call this after a successful checkout if `get_buyer_profile` returned `default_shipping_address: null`.** The address is persisted server-side against the buyer token — the buyer never needs to re-enter it. Use the same address that was passed to `set_shipping_address` for this order.
| Argument | Type | Description |
|---|---|---|
| address* | object | The shipping address to save — same structure as set_shipping_address |
| buyer_token* | string | The buyer's kfb_live_... token |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"buyer_token",
"address"
],
"properties": {
"address": {
"type": "object",
"required": [
"name",
"line1",
"city",
"region",
"postal_code"
],
"properties": {
"city": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"name": {
"type": "string",
"maxLength": 150,
"minLength": 1,
"description": "Buyer's full name"
},
"line1": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Street address line 1"
},
"line2": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Street address line 2"
},
"phone": {
"anyOf": [
{
"type": "string",
"maxLength": 30
},
{
"type": "null"
}
]
},
"region": {
"type": "string",
"maxLength": 50,
"minLength": 1,
"description": "State/region code, e.g. 'CA'"
},
"country": {
"type": "string",
"default": "US",
"maxLength": 2,
"minLength": 2,
"description": "ISO 3166-1 alpha-2 country code"
},
"postal_code": {
"type": "string",
"maxLength": 20,
"minLength": 3
}
},
"description": "The shipping address to save — same structure as set_shipping_address",
"additionalProperties": false
},
"buyer_token": {
"type": "string",
"minLength": 1,
"description": "The buyer's kfb_live_... token"
}
},
"additionalProperties": false
}Search or browse Kifly's product catalog across every seller on the network. Multilingual semantic search (100+ languages); omit `q` to browse recent listings. Pass `q` as an array (up to 5) to try several phrasings in ONE call instead of N searches. Too many hits? Ask once with `facets: true`, then narrow with `delivers_to`, price, `category` or `seller_handle`; page with `cursor` when `kifly:hasMore`. Returns a JSON-LD ItemList. **Rules that matter before you read the response:** - Cart every product the buyer wants: checkout hands them to pay with the cart ready. `kifly:purchasable: false` is still buyable, paid on the seller's own site. `availability` is STOCK; `kifly:purchasable` is WHERE they pay. - On `availability:OutOfStock`, still show it if asked, say it is sold out, and never cart it (`add_to_cart` returns 409). - When a product has several size/style variants, ask the buyer ONE option axis at a time (`kifly:productOptions` gives the axes in the seller's order). Never recite the combination matrix. - On an empty result, read `kifly:emptyReason`: say nothing matched rather than guessing, then offer `kifly:suggestions` (related, NOT matches). Items with `kifly:offNetwork` are outside retailers': relay `kifly:affiliateDisclosure`, cart as usual. **Full field reference: resource `kifly://docs/search-response`** (seller map, delivery coverage, variants, capped fields, every `kifly:` extension). Fetch it once for field-level detail.
| Argument | Type | Description |
|---|---|---|
| q | any | Query, or up to 5 queries unioned by best relevance. Omit to browse. |
| meta | object | Who is calling. See kifly://docs/mcp. |
| limit | integer | Max results per page (default 10). |
| cursor |
Requires `cart:write`, or no key: send `meta.ucp-agent.profile`. Persist a shipping address on the cart and confirm the seller can deliver to it. **Call BEFORE `checkout`.** Returns `delivery_eligible`. When true it also returns `cart_total_with_delivery_cents` — quote that full price before sending the buyer to pay, unless `shipping_priced_at` is `merchant_checkout`: then fee and total are null because the seller's own checkout prices shipping; say so, never call shipping free. When false, no address is saved and `delivery_coverage` says where the seller does cover, so you can retry with a covered address. Coverage semantics: `kifly://docs/delivery`.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
| cart_id* | string | Cart ID from create_cart |
| idempotency_key | string | Your own retry key (16-64 chars). Resend the SAME key to retry safely. |
| shipping_address* | object | Structured shipping address collected conversationally from the buyer |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id",
"shipping_address"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
},
"cart_id": {
"type": "string",
"description": "Cart ID from create_cart"
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
},
"shipping_address": {
"type": "object",
"required": [
"name",
"line1",
"city",
"region",
"postal_code"
],
"properties": {
"city": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"name": {
"type": "string",
"maxLength": 150,
"minLength": 1,
"description": "Buyer's full name"
},
"line1": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Street address line 1"
},
"line2": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Street address line 2 (apt, suite)"
},
"phone": {
"anyOf": [
{
"type": "string",
"maxLength": 30
},
{
"type": "null"
}
],
"description": "Optional contact phone for delivery"
},
"region": {
"type": "string",
"maxLength": 50,
"minLength": 1,
"description": "US state code (e.g. 'CA', 'NE') — matched against seller's delivery_coverage.states"
},
"country": {
"type": "string",
"default": "US",
"maxLength": 2,
"minLength": 2,
"description": "ISO 3166-1 alpha-2 country code"
},
"postal_code": {
"type": "string",
"maxLength": 20,
"minLength": 3,
"description": "Postal/ZIP code"
}
},
"description": "Structured shipping address collected conversationally from the buyer",
"additionalProperties": false
}
},
"additionalProperties": false
}Send structured feedback to the Kifly team. **No API key required** — send `meta.ucp-agent.profile` and this works with no credential at all. **Call after a confusing response, a dead-end, or a successful workaround you had to invent** — it's how we improve the agent surface, and a report from the moment you were stuck is worth more to us than a working purchase. Fire-and-forget: returns 202 immediately, no blocking, safe to skip if it would add latency to a user-facing flow. `category` and `severity` are required enums (don't free-form them). Include `context` with what you were doing (tool called, query used, response shape, what you expected). Add `suggested_fix` only if you have a concrete idea. Rate-limited.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
| contact | object | Optional. Where to reach you if we have a question about this report. Needs at least one field. |
| context | object | Reproducible signal: { tool, query, response_snippet, expected }. Auto-fill from what you just did. |
| message* | string | Plain-language description. Be specific about what happened and why it's a problem. |
| category* | string | What kind of issue. Pick the closest match — don't invent new categories. |
| severity* | string | blocker = can't complete the task. friction = degraded UX. nice_to_have = improvement idea. |
Requires `cart:write`, or no key: send `meta.ucp-agent.profile`. Change the quantity of a line item in an open cart, or remove it entirely. Set `quantity` to 0 to remove the item. Get the `item_id` from `get_cart` or the `cart` field in the `add_to_cart` response. Returns the updated cart state. **The per-item quantity ceiling applies here too — call `get_platform_limits` to check the current limit.** Exceeding it returns 400 `QUANTITY_EXCEEDS_LIMIT`.
| Argument | Type | Description |
|---|---|---|
| meta | object | Who is calling. See kifly://docs/mcp. |
| cart_id* | string | Cart ID from create_cart |
| item_id* | string | Item ID from get_cart or add_to_cart response |
| quantity* | integer | New quantity (0 removes the item) |
| idempotency_key | string | Your own retry key (16-64 chars). Resend the SAME key to retry safely. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id",
"item_id",
"quantity"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
},
"cart_id": {
"type": "string",
"description": "Cart ID from create_cart"
},
"item_id": {
"type": "string",
"description": "Item ID from get_cart or add_to_cart response"
},
"quantity": {
"type": "integer",
"minimum": 0,
"description": "New quantity (0 removes the item)"
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
}
},
"additionalProperties": false
}Verify the 6-digit code a returning buyer received by email (from `request_buyer_code`). On success returns `{ buyer_token, buyer_profile_id }` — pass the `buyer_token` to `get_buyer_profile` to auto-fill their saved name + shipping address, and to `checkout` to pre-fill their email on the payment link. Fails with `invalid_otp` if the code is wrong or expired (ask them to re-check, or call `request_buyer_code` again). Requires the `buyer:write` capability.
| Argument | Type | Description |
|---|---|---|
| code* | string | The 6-digit code the buyer received by email |
| email* | string | The buyer's email address (same one used for request_buyer_code) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email",
"code"
],
"properties": {
"code": {
"type": "string",
"pattern": "^\\d{6}$",
"description": "The 6-digit code the buyer received by email"
},
"email": {
"type": "string",
"format": "email",
"description": "The buyer's email address (same one used for request_buyer_code)"
}
},
"additionalProperties": false
}| idempotency_key |
| string |
| Your own retry key (16-64 chars). Resend the SAME key to retry safely. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Buyer's email, collected conversationally. Pre-fills the Stripe Checkout email field so the buyer doesn't retype it. This is ALL you need to pre-fill email — ask the buyer for their email, never for a token."
},
"cart_id": {
"type": "string",
"description": "Cart ID from create_cart"
},
"buyer_token": {
"type": "string",
"description": "INTERNAL token (kfb_live_...) minted by register_buyer / verify_buyer — resolves the buyer's saved profile and pre-fills their email on the payment link. NEVER ask the buyer to paste this. Omit it unless you already obtained one programmatically this session; to pre-fill email, use `email` instead."
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
}
},
"additionalProperties": false
}| shipping_address* |
| object |
| Structured shipping address collected conversationally from the buyer |
| external_customer_ref | string | Embedded-commerce pass-through: the seller's own opaque customer id for a cart from their embed widget. Omit unless you are the embed flow. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"items",
"shipping_address"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"variant_id",
"quantity"
],
"properties": {
"quantity": {
"type": "integer",
"minimum": 1,
"description": "Quantity to add"
},
"variant_id": {
"type": "string",
"minLength": 1,
"description": "Product variant ID from search_products results"
},
"measure_amount": {
"type": "number",
"description": "Sold-by-measure amount (e.g. 0.4 oz) for variants priced by measure; omit for fixed-price variants",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"maxItems": 50,
"minItems": 1,
"description": "Line items to add — all must belong to the same seller"
},
"seller_handle": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"maxLength": 40,
"minLength": 3,
"description": "Seller handle from search_products. REQUIRED for network tokens; omit for seller-scoped tokens (their own seller is implicit)."
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
},
"shipping_address": {
"type": "object",
"required": [
"name",
"line1",
"city",
"region",
"postal_code"
],
"properties": {
"city": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"name": {
"type": "string",
"maxLength": 150,
"minLength": 1,
"description": "Buyer's full name"
},
"line1": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Street address line 1"
},
"line2": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Street address line 2 (apt, suite)"
},
"phone": {
"anyOf": [
{
"type": "string",
"maxLength": 30
},
{
"type": "null"
}
],
"description": "Optional contact phone for delivery"
},
"region": {
"type": "string",
"maxLength": 50,
"minLength": 1,
"description": "US state code (e.g. 'CA', 'NE') — matched against seller's delivery_coverage.states"
},
"country": {
"type": "string",
"default": "US",
"maxLength": 2,
"minLength": 2,
"description": "ISO 3166-1 alpha-2 country code"
},
"postal_code": {
"type": "string",
"maxLength": 20,
"minLength": 3,
"description": "Postal/ZIP code"
}
},
"description": "Structured shipping address collected conversationally from the buyer",
"additionalProperties": false
},
"external_customer_ref": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Embedded-commerce pass-through: the seller's own opaque customer id for a cart from their embed widget. Omit unless you are the embed flow."
}
},
"additionalProperties": false
}| buyer_token* | string | The buyer's kfb_live_ token. Required — feature requests must come from a registered buyer. |
| contact_phone | string | Optional phone number IF the buyer offers one for follow-up. Name + email come from their profile — never ask for those. |
| proposed_solution | string | Optional. The buyer's idea for a fix, kept separate from the problem. Leave blank if they only described the pain. |
| current_workaround | string | Optional. What the buyer does today instead. Leave blank if there's no workaround. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"buyer_token",
"problem",
"impact",
"category",
"severity"
],
"properties": {
"impact": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Why it matters: who it affects, how often, what it costs them today."
},
"context": {
"type": "object",
"description": "Optional signal about the conversation: { goal, seller, last_tool }. Auto-fill from what you were doing.",
"additionalProperties": {}
},
"problem": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "The pain in the buyer's own terms — what's broken or missing for them. NOT the proposed fix."
},
"category": {
"enum": [
"discoverability",
"response_shape",
"tool_description",
"latency",
"error_handling",
"missing_capability",
"other"
],
"type": "string",
"description": "Closest match for the area of the request. Don't invent new categories."
},
"severity": {
"enum": [
"blocker",
"friction",
"nice_to_have"
],
"type": "string",
"description": "blocker = can't accomplish the goal at all. friction = works but painful. nice_to_have = improvement idea."
},
"buyer_token": {
"type": "string",
"minLength": 1,
"description": "The buyer's kfb_live_ token. Required — feature requests must come from a registered buyer."
},
"contact_phone": {
"type": "string",
"maxLength": 50,
"minLength": 1,
"description": "Optional phone number IF the buyer offers one for follow-up. Name + email come from their profile — never ask for those."
},
"proposed_solution": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Optional. The buyer's idea for a fix, kept separate from the problem. Leave blank if they only described the pain."
},
"current_workaround": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Optional. What the buyer does today instead. Leave blank if there's no workaround."
}
},
"additionalProperties": false
}| string |
| kifly:nextCursor from the previous page |
| facets | boolean | Add kifly:facets counts over all matches |
| sort_by | string | Sort order (default: relevance) |
| category | string | Category, e.g. a kifly:facets value |
| delivers_to | object | Only sellers delivering here, e.g. {country:'US',region:'CA'} |
| in_stock_only | boolean | In-stock only |
| seller_handle | string | Scope to one seller's catalog |
| max_price_cents | integer | Max price, cents |
| min_price_cents | integer | Min price, cents |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"q": {
"anyOf": [
{
"type": "string",
"maxLength": 500,
"minLength": 1
},
{
"type": "array",
"items": {
"type": "string",
"maxLength": 500,
"minLength": 1
},
"maxItems": 5,
"minItems": 1
}
],
"description": "Query, or up to 5 queries unioned by best relevance. Omit to browse."
},
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
},
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Max results per page (default 10)."
},
"cursor": {
"type": "string",
"description": "kifly:nextCursor from the previous page"
},
"facets": {
"type": "boolean",
"description": "Add kifly:facets counts over all matches"
},
"sort_by": {
"enum": [
"relevance",
"price_asc",
"price_desc",
"newest"
],
"type": "string",
"description": "Sort order (default: relevance)"
},
"category": {
"type": "string",
"description": "Category, e.g. a kifly:facets value"
},
"delivers_to": {
"type": "object",
"required": [
"country"
],
"properties": {
"city": {
"type": "string"
},
"region": {
"type": "string"
},
"country": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"postal_code": {
"type": "string"
}
},
"description": "Only sellers delivering here, e.g. {country:'US',region:'CA'}",
"additionalProperties": false
},
"in_stock_only": {
"type": "boolean",
"description": "In-stock only"
},
"seller_handle": {
"type": "string",
"description": "Scope to one seller's catalog"
},
"max_price_cents": {
"type": "integer",
"minimum": 0,
"description": "Max price, cents"
},
"min_price_cents": {
"type": "integer",
"minimum": 0,
"description": "Min price, cents"
}
},
"additionalProperties": false
}| agent_name | string | Optional. Your agent's name and who runs it (e.g. "ShopBot by Acme"), so we know who reported this. |
| suggested_fix | string | Optional. Only include if you have a concrete idea. Leave blank if you only have a complaint. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"category",
"severity",
"message"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "https:// URL of your agent's UCP profile. No API key needed."
}
},
"additionalProperties": false
}
},
"description": "Who is calling. See kifly://docs/mcp.",
"additionalProperties": true
},
"contact": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 512
},
"email": {
"type": "string",
"format": "email",
"maxLength": 254
},
"handle": {
"type": "string",
"maxLength": 80,
"minLength": 1
}
},
"description": "Optional. Where to reach you if we have a question about this report. Needs at least one field.",
"additionalProperties": false
},
"context": {
"type": "object",
"description": "Reproducible signal: { tool, query, response_snippet, expected }. Auto-fill from what you just did.",
"additionalProperties": {}
},
"message": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Plain-language description. Be specific about what happened and why it's a problem."
},
"category": {
"enum": [
"discoverability",
"response_shape",
"tool_description",
"latency",
"error_handling",
"missing_capability",
"other"
],
"type": "string",
"description": "What kind of issue. Pick the closest match — don't invent new categories."
},
"severity": {
"enum": [
"blocker",
"friction",
"nice_to_have"
],
"type": "string",
"description": "blocker = can't complete the task. friction = degraded UX. nice_to_have = improvement idea."
},
"agent_name": {
"type": "string",
"maxLength": 80,
"minLength": 1,
"description": "Optional. Your agent's name and who runs it (e.g. \"ShopBot by Acme\"), so we know who reported this."
},
"suggested_fix": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Optional. Only include if you have a concrete idea. Leave blank if you only have a complaint."
}
},
"additionalProperties": false
}