Kifly — Agentic Commerce & Payments

Official21 toolsLive

by kifly

Multi-seller shopping for AI agents. Settle via Stripe MPP or x402 USDC on Base. Hosted.

ai.kifly/mcp (MCP Server)

The ai.kifly/mcp Model Context Protocol (MCP) server provides “Multi-seller shopping for AI agents.” It is hosted as a service, with settlement options including Stripe MPP or x402 USDC on Base. The server is identified by the slug ai-kifly-mcp and includes 21 tools.

🛠️ Key Features

Multi-seller shopping for AI agents
Hosted deployment
21 tools
Settlement via Stripe MPP or x402 USDC on Base

🚀 Use Cases

Enabling AI agents to perform multi-seller shopping flows
Integrating shopping settlement for agent workflows using Stripe MPP or x402 USDC on Base

⚡ Developer Benefits

Tool-based MCP integration (21 available tools)
Clear settlement pathways for payments (Stripe MPP, x402 USDC on Base)

⚠️ Limitations

No additional details provided about specific tools, authentication, or integration surface beyond the tool count and settlement options

Captured live from the server via tools/list.

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. In cross-seller (network) results, each item's `kifly:seller` is just the seller's handle — look it up once in the ItemList's `kifly:sellers` map (keyed by handle) to read `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). `delivery_coverage.cities` may be capped — compare `cities.length` against `city_count` and call `get_seller` for the full list if fewer. Seller-scoped results carry the full record once at the list level (`kifly:seller` on the ItemList itself) instead. Each item also carries `kifly:variantId`. When a product has 2+ size/style variants, `kifly:hasVariant` lists each with its own `kifly:variantId` — pass the matching one to `create_cart`/`add_to_cart` for the buyer's chosen size/color (capped at 20 variants; `kifly:variantCount` is set if the product has more — vanishingly rare today). `image` is capped to 2 URLs per product — if `kifly:imageCount` is present, there are more than shown (not retrievable via this API; the cap is a hard limit, not a paginated detail). Each result's `offers` carries `kifly:purchasable`: when **false**, the seller is discovery-only (directory-tier or not yet able to charge) — checkout will hand off / fail, so present it as a referral, not a buy. `availability:InStock` is about stock, NOT buyability — read `kifly:purchasable` to decide whether to route the buyer to checkout. **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`.**

Parameters9

q	any	optional	Natural-language query, or an array of up to 5 queries to explore in ONE call (results are unioned by best relevance). Omit to browse recent listings.
limit	integer	optional	Max results per page (default 10).
sort_by	string	optional	Sort order (default: relevance)
min_price_cents	integer	optional	Minimum price filter in cents
max_price_cents	integer	optional	Maximum price filter in cents
in_stock_only	boolean	optional	Only return products with available inventory
category	string	optional	Case-insensitive category filter (e.g. 'fashion', 'Electronics'). Matches the seller-assigned category value.
seller_handle	string	optional	Scope results to one seller's catalog (e.g. 'bay-clothing-district'). For network tokens only; ignored for seller-scoped tokens.
cursor	string	optional	Pagination cursor from kifly:nextCursor in a previous browse response. Omit on the first call.

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "minItems": 1,
          "maxItems": 5
        }
      ],
      "description": "Natural-language query, or an array of up to 5 queries to explore in ONE call (results are unioned by best relevance). Omit to browse recent listings."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "Max results per page (default 10)."
    },
    "sort_by": {
      "type": "string",
      "enum": [
        "relevance",
        "price_asc",
        "price_desc",
        "newest"
      ],
      "description": "Sort order (default: relevance)"
    },
    "min_price_cents": {
      "type": "integer",
      "minimum": 0,
      "description": "Minimum price filter in cents"
    },
    "max_price_cents": {
      "type": "integer",
      "minimum": 0,
      "description": "Maximum price filter in cents"
    },
    "in_stock_only": {
      "type": "boolean",
      "description": "Only return products with available inventory"
    },
    "category": {
      "type": "string",
      "description": "Case-insensitive category filter (e.g. 'fashion', 'Electronics'). Matches the seller-assigned category value."
    },
    "seller_handle": {
      "type": "string",
      "description": "Scope results to one seller's catalog (e.g. 'bay-clothing-district'). For network tokens only; ignored for seller-scoped tokens."
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor from kifly:nextCursor in a previous browse response. Omit on the first call."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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'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 whether this seller can complete a real Kifly checkout — `false`/`"external"` means directory-tier: checkout will hand off to the seller's own site instead of charging, so present the flow as a referral, not a purchase. Cart-building still works either way (needed to generate the handoff's per-product links), and the same flag rides every add_to_cart/get_cart response on this cart too.

Parameters1

seller_handle

string

optional

Seller handle (e.g. 'bay-clothing-district'). Required for network tokens; ignored for seller-scoped tokens.

Raw schema

{
  "type": "object",
  "properties": {
    "seller_handle": {
      "type": "string",
      "description": "Seller handle (e.g. 'bay-clothing-district'). Required for network tokens; ignored for seller-scoped tokens."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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. `cart.kifly_purchasable` (and `cart.fulfillment`) carries the same non-transactable signal as create_cart's `seller` field — check it before telling the buyer this is a real purchase.

Parameters3

cart_id	string	required	Cart ID from create_cart
variant_id	string	required	Product variant ID from search_products results
quantity	integer	optional	Quantity to add

Raw schema

{
  "type": "object",
  "properties": {
    "cart_id": {
      "type": "string",
      "description": "Cart ID from create_cart"
    },
    "variant_id": {
      "type": "string",
      "description": "Product variant ID from search_products results"
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "default": 1,
      "description": "Quantity to add"
    }
  },
  "required": [
    "cart_id",
    "variant_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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. `kifly_purchasable: false` (`fulfillment: "external"`) means checkout on this cart will hand off to the seller's own site instead of charging — say so before the buyer expects a real purchase.

Parameters1

cart_id

string

required

Cart ID from create_cart

Raw schema

{
  "type": "object",
  "properties": {
    "cart_id": {
      "type": "string",
      "description": "Cart ID from create_cart"
    }
  },
  "required": [
    "cart_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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

Parameters3

cart_id	string	required	Cart ID from create_cart
item_id	string	required	Item ID from get_cart or add_to_cart response
quantity	integer	required	New quantity (0 removes the item)

Raw schema

{
  "type": "object",
  "properties": {
    "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)"
    }
  },
  "required": [
    "cart_id",
    "item_id",
    "quantity"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

cart_id	string	required	Cart ID from create_cart
shipping_address	object	required	Structured shipping address collected conversationally from the buyer

Raw schema

{
  "type": "object",
  "properties": {
    "cart_id": {
      "type": "string",
      "description": "Cart ID from create_cart"
    },
    "shipping_address": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 150,
          "description": "Buyer's full name"
        },
        "line1": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Street address line 1"
        },
        "line2": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ],
          "description": "Street address line 2 (apt, suite)"
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "region": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50,
          "description": "US state code (e.g. 'CA', 'NE') — matched against seller's delivery_coverage.states"
        },
        "postal_code": {
          "type": "string",
          "minLength": 3,
          "maxLength": 20,
          "description": "Postal/ZIP code"
        },
        "country": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2,
          "default": "US",
          "description": "ISO 3166-1 alpha-2 country code"
        },
        "phone": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 30
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional contact phone for delivery"
        }
      },
      "required": [
        "name",
        "line1",
        "city",
        "region",
        "postal_code"
      ],
      "additionalProperties": false,
      "description": "Structured shipping address collected conversationally from the buyer"
    }
  },
  "required": [
    "cart_id",
    "shipping_address"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

quick_buy

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: when `delivery_eligible: true` it carries `cart_total_with_delivery_cents` (quote it before sending the buyer to pay); when `false` it carries `reason` + `delivery_coverage` and NO address is saved, so you can call quick_buy again (or set_shipping_address) with a covered address on info you already have. **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.

Parameters4

seller_handle	string	optional	Seller handle from search_products. REQUIRED for network tokens; omit for seller-scoped tokens (their own seller is implicit).
items	array	required	Line items to add — all must belong to the same seller
shipping_address	object	required	Structured shipping address collected conversationally from the buyer
external_customer_ref	string	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "seller_handle": {
      "type": "string",
      "minLength": 3,
      "maxLength": 40,
      "pattern": "^[a-z0-9-]+$",
      "description": "Seller handle from search_products. REQUIRED for network tokens; omit for seller-scoped tokens (their own seller is implicit)."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "variant_id": {
            "type": "string",
            "minLength": 1,
            "description": "Product variant ID from search_products results"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "description": "Quantity to add"
          },
          "measure_amount": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Sold-by-measure amount (e.g. 0.4 oz) for variants priced by measure; omit for fixed-price variants"
          }
        },
        "required": [
          "variant_id",
          "quantity"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "Line items to add — all must belong to the same seller"
    },
    "shipping_address": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 150,
          "description": "Buyer's full name"
        },
        "line1": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Street address line 1"
        },
        "line2": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ],
          "description": "Street address line 2 (apt, suite)"
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "region": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50,
          "description": "US state code (e.g. 'CA', 'NE') — matched against seller's delivery_coverage.states"
        },
        "postal_code": {
          "type": "string",
          "minLength": 3,
          "maxLength": 20,
          "description": "Postal/ZIP code"
        },
        "country": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2,
          "default": "US",
          "description": "ISO 3166-1 alpha-2 country code"
        },
        "phone": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 30
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional contact phone for delivery"
        }
      },
      "required": [
        "name",
        "line1",
        "city",
        "region",
        "postal_code"
      ],
      "additionalProperties": false,
      "description": "Structured shipping address collected conversationally from the buyer"
    },
    "external_customer_ref": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "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."
    }
  },
  "required": [
    "items",
    "shipping_address"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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`). **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.** On success: `payment_rail` tells you which outcome you got. `'stripe-checkout'` — a real Kifly purchase: returns `payment_url` (the Stripe link the BUYER must open and pay), `session_id` for `order_status`, and amount breakdown. **Relay the link and tell the buyer they need to complete payment themselves — do not imply the purchase is done until `order_status` reports `paid`.** `'directory-handoff'` — this seller is discovery-only (`kifly_purchasable: false` on the cart, as already signaled by create_cart/add_to_cart/get_cart); there is NO `payment_url`/`session_id`. Instead a `handoff` object carries `seller` (name, handle, storefront_url) and `items` (each with a tracked `link` to the product on the seller's own site, or null — fall back to `seller.storefront_url`), plus a `disclaimer` to relay verbatim. Present this as a referral to complete the purchase off-platform, not as a completed Kifly order. **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 to pre-fill the saved email: `'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.

Parameters3

cart_id	string	required	Cart ID from create_cart
email	string	optional	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.
buyer_token	string	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "cart_id": {
      "type": "string",
      "description": "Cart ID from create_cart"
    },
    "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."
    },
    "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."
    }
  },
  "required": [
    "cart_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

register_buyer

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.

Parameters2

email	string	required	Buyer's email address
name	string	required	Buyer's full name

Raw schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "description": "Buyer's email address"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Buyer's full name"
    }
  },
  "required": [
    "email",
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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 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 }` — for the buyer's privacy the response is identical whether or not the email has a Kifly account (so it can't be used to probe who shops here), and a code is only actually emailed if an account exists. 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).

Parameters1

string

required

The returning buyer's email address

Raw schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "description": "The returning buyer's email address"
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

email	string	required	The buyer's email address (same one used for request_buyer_code)
code	string	required	The 6-digit code the buyer received by email

Raw schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "description": "The buyer's email address (same one used for request_buyer_code)"
    },
    "code": {
      "type": "string",
      "pattern": "^\\d{6}$",
      "description": "The 6-digit code the buyer received by email"
    }
  },
  "required": [
    "email",
    "code"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

buyer_token

string

required

The buyer's kfb_live_... token from their Kifly account

Raw schema

{
  "type": "object",
  "properties": {
    "buyer_token": {
      "type": "string",
      "minLength": 1,
      "description": "The buyer's kfb_live_... token from their Kifly account"
    }
  },
  "required": [
    "buyer_token"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

buyer_token	string	required	The buyer's kfb_live_... token from their Kifly account
since	string	optional	ISO-8601 timestamp. Only return orders updated after this — pass the time of your last check to get the delta.
limit	integer	optional	Max orders to return (default 20, max 50).

Raw schema

{
  "type": "object",
  "properties": {
    "buyer_token": {
      "type": "string",
      "minLength": 1,
      "description": "The buyer's kfb_live_... token from their Kifly account"
    },
    "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."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Max orders to return (default 20, max 50)."
    }
  },
  "required": [
    "buyer_token"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

buyer_token	string	required	The buyer's kfb_live_... token
address	object	required	The shipping address to save — same structure as set_shipping_address

Raw schema

{
  "type": "object",
  "properties": {
    "buyer_token": {
      "type": "string",
      "minLength": 1,
      "description": "The buyer's kfb_live_... token"
    },
    "address": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 150,
          "description": "Buyer's full name"
        },
        "line1": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Street address line 1"
        },
        "line2": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ],
          "description": "Street address line 2"
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "region": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50,
          "description": "State/region code, e.g. 'CA'"
        },
        "postal_code": {
          "type": "string",
          "minLength": 3,
          "maxLength": 20
        },
        "country": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2,
          "default": "US",
          "description": "ISO 3166-1 alpha-2 country code"
        },
        "phone": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 30
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "name",
        "line1",
        "city",
        "region",
        "postal_code"
      ],
      "additionalProperties": false,
      "description": "The shipping address to save — same structure as set_shipping_address"
    }
  },
  "required": [
    "buyer_token",
    "address"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

category	string	required	What kind of issue. Pick the closest match — don't invent new categories.
severity	string	required	blocker = can't complete the task. friction = degraded UX. nice_to_have = improvement idea.
message	string	required	Plain-language description. Be specific about what happened and why it's a problem.
context	object	optional	Reproducible signal: { tool, query, response_snippet, expected }. Auto-fill from what you just did.
suggested_fix	string	optional	Optional. Only include if you have a concrete idea. Leave blank if you only have a complaint.

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "discoverability",
        "response_shape",
        "tool_description",
        "latency",
        "error_handling",
        "missing_capability",
        "other"
      ],
      "description": "What kind of issue. Pick the closest match — don't invent new categories."
    },
    "severity": {
      "type": "string",
      "enum": [
        "blocker",
        "friction",
        "nice_to_have"
      ],
      "description": "blocker = can't complete the task. friction = degraded UX. nice_to_have = improvement idea."
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "Plain-language description. Be specific about what happened and why it's a problem."
    },
    "context": {
      "type": "object",
      "additionalProperties": {},
      "description": "Reproducible signal: { tool, query, response_snippet, expected }. Auto-fill from what you just did."
    },
    "suggested_fix": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "Optional. Only include if you have a concrete idea. Leave blank if you only have a complaint."
    }
  },
  "required": [
    "category",
    "severity",
    "message"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters9

buyer_token	string	required	The buyer's kfb_live_ token. Required — feature requests must come from a registered buyer.
problem	string	required	The pain in the buyer's own terms — what's broken or missing for them. NOT the proposed fix.
impact	string	required	Why it matters: who it affects, how often, what it costs them today.
category	string	required	Closest match for the area of the request. Don't invent new categories.
severity	string	required	blocker = can't accomplish the goal at all. friction = works but painful. nice_to_have = improvement idea.
current_workaround	string	optional	Optional. What the buyer does today instead. Leave blank if there's no workaround.
proposed_solution	string	optional	Optional. The buyer's idea for a fix, kept separate from the problem. Leave blank if they only described the pain.
contact_phone	string	optional	Optional phone number IF the buyer offers one for follow-up. Name + email come from their profile — never ask for those.
context	object	optional	Optional signal about the conversation: { goal, seller, last_tool }. Auto-fill from what you were doing.

Raw schema

{
  "type": "object",
  "properties": {
    "buyer_token": {
      "type": "string",
      "minLength": 1,
      "description": "The buyer's kfb_live_ token. Required — feature requests must come from a registered buyer."
    },
    "problem": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "The pain in the buyer's own terms — what's broken or missing for them. NOT the proposed fix."
    },
    "impact": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "Why it matters: who it affects, how often, what it costs them today."
    },
    "category": {
      "type": "string",
      "enum": [
        "discoverability",
        "response_shape",
        "tool_description",
        "latency",
        "error_handling",
        "missing_capability",
        "other"
      ],
      "description": "Closest match for the area of the request. Don't invent new categories."
    },
    "severity": {
      "type": "string",
      "enum": [
        "blocker",
        "friction",
        "nice_to_have"
      ],
      "description": "blocker = can't accomplish the goal at all. friction = works but painful. nice_to_have = improvement idea."
    },
    "current_workaround": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "Optional. What the buyer does today instead. Leave blank if there's no workaround."
    },
    "proposed_solution": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "Optional. The buyer's idea for a fix, kept separate from the problem. Leave blank if they only described the pain."
    },
    "contact_phone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50,
      "description": "Optional phone number IF the buyer offers one for follow-up. Name + email come from their profile — never ask for those."
    },
    "context": {
      "type": "object",
      "additionalProperties": {},
      "description": "Optional signal about the conversation: { goal, seller, last_tool }. Auto-fill from what you were doing."
    }
  },
  "required": [
    "buyer_token",
    "problem",
    "impact",
    "category",
    "severity"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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, city_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. This is the full profile — `cities` is never capped here (unlike `list_sellers`/`search_products`). **`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. **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.

Parameters1

handle

string

optional

Seller handle (case-insensitive, e.g. 'bay-clothing-district' or 'BayClothingDistrict'). Required for network tokens; ignored for seller-scoped tokens.

Raw schema

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "description": "Seller handle (case-insensitive, e.g. 'bay-clothing-district' or 'BayClothingDistrict'). Required for network tokens; ignored for seller-scoped tokens."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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

Parameters2

limit	integer	optional	Max sellers per page (default 20, max 50).
cursor	string	optional	Pagination cursor from kifly:nextCursor in a previous response. Omit on the first call.

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "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,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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. Call get_help if the buyer needs Kifly's support contact.

Parameters1

session_id

string

required

Stripe checkout session ID from the checkout tool response

Raw schema

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Stripe checkout session ID from the checkout tool response"
    }
  },
  "required": [
    "session_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Install

Tools (21)

search_productscreate_cartadd_to_cartget_cartupdate_cart_itemset_shipping_addressquick_buycheckout

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://kifly.ai/api/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://kifly.ai/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

ai.kifly/mcp (MCP Server)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

search_products

create_cart

add_to_cart

get_cart

update_cart_item

set_shipping_address

quick_buy

checkout

register_buyer

request_buyer_code

verify_buyer

get_buyer_profile

list_orders

save_buyer_address

submit_feedback

request_feature

get_seller

list_sellers

get_platform_limits

order_status

get_help

Install

Remote endpoint

Related servers