Kifly MCP Integration Guide

Connect any MCP-compatible agent to Kifly's live product catalog using the Model Context Protocol over HTTP.

Endpoint

https://kifly.ai/api/mcp

Stateless StreamableHTTP transport. Every request is independent — no session state is held server-side between calls.

Authentication

Pick the credential by what you're building, not by what's simplest. The three paths return different data, and getting this wrong is silent — the wrong key doesn't error, it just quietly shows you less than the whole network.

Seller API key (kfa_live_) — your own store only

Generate one from the Kifly seller dashboard → Developer → API Keys. It authenticates as your store and only ever returns your catalog — search, list_sellers, and every other read are scoped to seller_id, by design (this is the boundary that keeps one seller's key from ever reading another seller's data). Requesting network scope on this key type is rejected at creation. If your agent needs to discover products across multiple sellers, this is the wrong key — use OAuth or a network key instead.

Authorization: Bearer kfa_live_xxxxxxxxxxxxxxxx

OAuth 2.1 — cross-network, per-user consent

Kifly runs a full OAuth 2.1 server with open dynamic client registration — no Kifly seller account needed to register a client, and no storefront of your own. This is the right choice for a buyer agent acting on behalf of a person who is present to consent.

PKCE S256 required. Refresh tokens rotate on each use. This is what claude.ai and other OAuth-requiring hosts negotiate automatically.

Network keys (kfn_live_) — headless agents, no human at connect time

If your agent runs unattended — no human in the loop to complete an OAuth consent screen — mint a network key instead:

POST /api/developer/network-keys
Authorization: <your Kifly session>
Content-Type: application/json

{ "name": "my-agent", "scopes": ["catalog:read:network", "cart:write", "checkout:write", "order:read", "buyer:write"] }

Returns a kfn_live_ token (seller_id is always null — this is a network-wide key, not tied to any one store) valid for one year. List and revoke your keys at GET/DELETE on the same path.

Minting is capped at 5 keys per hour and 10 active keys at a time per account — see Platform Limits. Revoke unused keys to stay under the ceiling.

No storefront required. Sign up at kifly.ai/dashboard/onboarding and choose "Building an agent instead of a store?" — a developer account registers with just a name and handle, is minting-ready immediately (no review, no waiting), and can never publish a product or take payouts. If you'd rather build against your own store, use a seller account with Developer Mode enabled instead (Dashboard → Developer → API Keys → "Enable developer mode") — either path lands here.

Authorization: Bearer kfn_live_xxxxxxxxxxxxxxxx

Connecting to your agent runtime

Each MCP host has its own process for registering an external MCP server, and these interfaces change frequently. Rather than walk you through steps that may already be out of date, we give you everything Kifly requires and link to each platform's official docs.

Server URL:

https://kifly.ai/api/mcp

Transport: StreamableHTTP (remote)

Authentication header (for hosts that let you set custom headers) — use whichever key type fits from the table above:

Authorization: Bearer kfa_live_xxxxxxxxxxxxxxxx   # your own store only
Authorization: Bearer kfn_live_xxxxxxxxxxxxxxxx   # whole network, headless

Hosts that require OAuth 2.1 (like claude.ai) negotiate it automatically — no header needed.

Claude — claude.ai web app

Use the one-click install button at the top of this page, or follow Anthropic's official guide:

→ Get started with custom connectors using remote MCP

Claude Desktop

→ Getting started with local MCP servers on Claude Desktop

Gemini / Google AI Studio

MCP support in Gemini is available at the API/SDK level. See Google's official documentation:

→ Gemini API — Deep Research & remote MCP tools

Other MCP-compatible runtimes

Use the server URL and auth header above. Most MCP hosts follow the same pattern — consult your runtime's official documentation for the exact steps.

Platform limits resource

At session start, read the kifly://platform/limits resource to know the current cart constraints before you begin a purchase flow:

{
  "max_item_quantity": 20,
  "max_cart_total_cents": 100000,
  "max_cart_total_usd": "1000.00"
}

These values are live — they may change without a code deploy. Exceeding max_item_quantity returns 400 quantity_exceeds_limit; exceeding the cart total returns 400 cart_total_exceeds_limit at checkout.

Available Tools (21)

Discovery

Cart lifecycle

Buyer identity

Platform & support

Recommended purchase flow

[1] read kifly://platform/limits (know the quantity + total caps)
[2] get_seller (optional — validate delivery coverage early)
[3] get_buyer_profile (returning buyer who already has a kfb_live_ token)
    OR request_buyer_code + verify_buyer (returning buyer — recover by email, no token)
    OR register_buyer + verify_buyer (new buyer — both end with a token to store)
[4] search_products
[5] create_cart
[6] add_to_cart (repeat for each item)
[7] get_cart (optional — review before asking for address)
[8] set_shipping_address → confirms delivery + returns total with delivery fee
[9] checkout → returns payment_url
[10] buyer pays at payment_url
[11] order_status (poll every 5s until paid or shipped)
[12] save_buyer_address (if get_buyer_profile returned null default_shipping_address)

set_shipping_address

{
  "cart_id": "cart_…",
  "shipping_address": {
    "name": "Ada Lovelace",
    "line1": "123 Market St",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94103",
    "country": "US"
  }
}

Returns delivery_eligible, cart_total_with_delivery_cents, and (when ineligible) the seller's delivery_coverage so you can tell the buyer which states and cities are covered.

Rate Limits

Responses include x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset headers. Limit breaches return 429 with a retry-after header.