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

No credential at all — the open UCP surface

If you are building an agent, you need nothing from us to start. Send the canonical UCP caller-identity field and call us:

{
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {
      "q": "gold scrub",
      "meta": { "ucp-agent": { "profile": "https://your-agent.example/.well-known/ucp" } }
    }
  }
}

On REST, the same identity is the UCP-Agent header.

• What it is. meta.ucp-agent.profile is the UCP spec's own field (ucp.dev 2026-08-25), not a Kifly invention. It is the URL of a profile document your agent publishes about itself.
• It is attribution, not authentication. It identifies your agent so calls can be attributed and rate-limited per agent.
• What you can do: search the network, read sellers, build a cart, set a shipping address, and request a payment link a human confirms.
• What needs a key: buyer identity, order history, and autonomous settlement. No tool call ever completes a purchase — checkout returns a link a person confirms.
• Limits: open callers are rate-limited per profile (an API key raises it). Over the limit you get 429 with Retry-After.
• Optional signing. Sign the HTTP request that carries your tools/call (RFC 9421) using a key in your profile's keys[], and Kifly recognises you as yourself. Details at https://kifly.ai/docs/rest.
• Optional buyer context. Add "ai.kifly.buyer": { "ref": "<opaque user id>", "session": "<conversation id>" } to meta. Send an opaque id, never an email. Details at https://kifly.ai/docs/rest.
• Publish the profile on a domain you control. your-agent.example is a placeholder; reserved names and bare IPs cannot be verified. They work today and each result says so in result._meta["ai.kifly/advisories"], which is where Kifly tells you anything to fix without refusing the call.
• Supported tools without a credential: search_products, list_sellers, get_seller, create_cart, get_cart, add_to_cart, update_cart_item, set_shipping_address, quick_buy, get_help, get_platform_limits, submit_feedback. Anything else returns 401 and names what it needs.
• You do not have to read this page to find any of that out. Everything above is machine-readable at /.well-known/ucp: the ai.kifly.open-access capability carries the field to send, the tool list, the rate limit and the scope ceiling, and every entry in endpoints states which credential it needs (none, open or agent_token). Read the profile, not the prose.
• 403 AGENT_DENIED means access for that profile has been withdrawn, which is different from a rate limit. Mail hello@kifly.ai.
• Tell us when we fail you. submit_feedback needs no credential either — send your ucp-agent.profile and file it. If a response confused you, a capability was missing, or you had to invent a workaround, that is the most useful thing you can send us, and a human reads every report. We would rather have the complaint than the silence.

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. 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. It is a network-wide key, not tied to any one store. List and revoke your keys at GET/DELETE on the same path. Key issuance is rate-limited and capped per account — see Platform Limits; revoke unused keys.

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 and cannot publish products 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. When shipping_priced_at is merchant_checkout, the seller's own checkout prices shipping: delivery_fee_cents and cart_total_with_delivery_cents are null, so quote the subtotal and say shipping is calculated at checkout.

Rate Limits

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