ai.kifly/mcp

search_products

Search or browse Kifly's product catalog. Multilingual semantic search (100+ languages). Returns a JSON-LD ItemList with `kifly:totalCatalogSize`. When empty, `kifly:emptyReason` is 'empty_catalog' | 'no_matches_for_query' — on 'no_matches_for_query' tell the buyer nothing matched rather than guessing, then offer `kifly:suggestions` (related products — NOT matches) and `kifly:availableCategories` (what the catalog carries) so you can help without a second search. Results carry `kifly:relevanceScore` [0–1]; a semantic similarity floor filters out irrelevant results automatically. Omit `q` to browse. Each result includes `kifly:seller` (with `delivery_fee_cents` and `delivery_coverage` — `nationwide:true` for all 50 states, a `states` list, or `coverage_configured:false` meaning the seller ships NOWHERE yet — empty `states` is NOT nationwide) and `kifly:variantId`. **You can read the delivery fee and check coverage from here — no need to call `set_shipping_address` just to learn the cost.** **Pagination (browse only):** when `kifly:hasMore` is true, pass `kifly:nextCursor` as `cursor` to fetch the next page. **Seller filter:** pass `seller_handle` to scope results to one seller. **Category filter:** free-text, case-insensitive (e.g. 'fashion'). **Multiple queries:** pass `q` as an array (up to 5) to try several phrasings in one call instead of N separate searches. **Before checkout, call `set_shipping_address`.**

create_cart

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 carries `kifly:seller.handle`) 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.

add_to_cart

Requires `checkout:write` scope. 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.

get_cart

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.

update_cart_item

Requires `checkout:write` scope. 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`.

set_shipping_address

Requires `checkout:write` scope. Persist a shipping address on the cart and confirm whether the seller can deliver to it. **Call BEFORE `checkout`.** Returns `delivery_eligible: true/false`. When false, `delivery_coverage: { states, cities }` tells you exactly which US states and cities the seller covers — tell the buyer where coverage is available. When true, returns `cart_total_with_delivery_cents` so you can quote the full price (item subtotal + flat delivery fee) before sending the buyer to pay.

checkout

Requires `checkout:write` scope. **Requires `set_shipping_address` to have been called first.** Returns 400 `invalid_shipping` if no address is on the cart, or 400 `delivery_unavailable` if the buyer's address is outside the seller's coverage. Cart total must not exceed the platform cap (`kifly://platform/limits`). On success: returns `payment_url` (Stripe link), `session_id` for `order_status`, and amount breakdown. **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.** `buyer_token_status` in the response reports whether an (internal) token was applied: `'resolved'` / `'invalid'` / `'none'` — an invalid token is NOT an error response. On 502/503 errors, check `retryable: true` in the body — those are transient upstream faults; wait `retry_after_seconds` then retry once.

register_buyer

Register a new buyer so they can be recognized across future purchases without re-entering their details. Takes the buyer's email and name, creates a Kifly buyer profile, and returns a `buyer_token` (`kfb_live_...`). **Store this token and pass it to `checkout` on every future order** — it pre-fills the buyer's email on the secure Stripe payment link so they skip re-entering it. Also pass it to `get_buyer_profile` to auto-fill name and shipping on repeat visits. Each call mints a new token; all tokens for the same buyer remain valid.

request_buyer_code

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. 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`. Returns `{ sent: true }`. If the email has no account yet, fails with `buyer_not_found` — in that case call `register_buyer` instead. Requires the `buyer:write` capability (marketplace/network keys).

verify_buyer

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.

get_buyer_profile

Retrieve a repeat buyer's saved name, email, and default shipping address. **At the start of every purchase flow, ask the buyer in plain language: 'Are you a returning Kifly shopper? What's the email on your Kifly account?' — never ask them to paste a token.** If they have a Kifly account, recover it by email: call `request_buyer_code` with their email, ask them for the 6-digit code we email them, then call `verify_buyer` to obtain their `buyer_token`, and finally call this tool with that token to auto-fill name, email, and shipping — they skip all manual data entry. (Alternative if email verification isn't available: send them the one-click sign-in link `https://kifly.ai/buyer?return_url=<encoded_current_chat_url>` — they sign in with Google and return with their details; the same link creates an account if they're new.) Use the returned `name` and `default_shipping_address` to auto-fill `set_shipping_address`. Pass the `buyer_token` to `checkout` so Stripe pre-fills their email. Returns `{ name, email, default_shipping_address }` where `default_shipping_address` may be null if the buyer hasn't saved one yet — if null, collect the address normally then call `save_buyer_address` so it's pre-filled next time.

list_orders

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.

save_buyer_address

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.

submit_feedback

Send structured feedback to the Kifly team. **Call after a confusing response, a dead-end, or a successful workaround you had to invent** — it's how we improve the agent surface. 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 to 10/min per agent token; everything is reviewed before influencing anything.

request_feature

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.

get_seller

Retrieve a seller's public profile: name, location (city/region/country), storefront URL, delivery fee, delivery coverage, and catalog size. **Call this before `create_cart` or `set_shipping_address` to validate that the seller ships to the buyer's area or to set expectations about catalog size.** `delivery_coverage` is `{ states, cities, nationwide, state_count, coverage_configured }` — the US state codes (e.g. 'CA', 'NE') and city names the seller delivers to; an address is eligible when its region matches a covered state OR its city matches a covered city. **`coverage_configured: false` means the seller has set up NO delivery yet — they ship NOWHERE; never tell the buyer they ship anywhere (an empty `states` list is NOT nationwide). `nationwide: true` means all 50 states, with `states` omitted to save space.** `delivery_fee_cents` is the flat fee added at checkout; `catalog_size` is the total number of products listed. `delivery_zones` (legacy postal-code list) is still returned for backward compatibility but new agents should read `delivery_coverage`. **For network (cross-seller) tokens, pass `handle` to name which seller you're asking about** (e.g. `handle: 'bay-clothing-district'`). Handle lookup is case-insensitive — 'BayClothingDistrict' and 'bayclothingdistrict' both resolve. Seller-scoped tokens may omit `handle` — their own seller is implicit.

list_sellers

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

get_platform_limits

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. The limits are operator-configurable; always read them at runtime rather than hardcoding.

No parameters.

order_status

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. Every response includes a `support` field with Kifly's website and contact email — surface this to the buyer if they have questions about their order.

get_help

Get Kifly's website and support contact email. Call this if you are stuck, hit an unresolvable error, or the buyer asks how to reach a human. Returns the website URL and support email — always share both with the buyer.

No parameters.