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

Two options. Use whichever fits your agent runtime.

Option A — Static API key (simplest)

Generate a key from the Kifly seller dashboard → Settings → API Keys. Keys start with kfa_live_.

Pass it as a Bearer token on every request:

Authorization: Bearer kfa_live_xxxxxxxxxxxxxxxx

Works in any HTTP client or MCP host that lets you set custom headers.

Option B — OAuth 2.1 (required for claude.ai)

Kifly runs a full OAuth 2.1 server. claude.ai and other agents that require OAuth use this flow automatically.

PKCE S256 required. Refresh tokens rotate on each use.

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

Authorization: Bearer kfa_live_xxxxxxxxxxxxxxxx

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 (18)

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 (new buyer, returns 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.