Agent Integration

Connect to Claude

One-click install the Kifly MCP server into Claude Desktop or Claude.ai.

You'll be prompted for your Kifly agent key. Generate one at /dashboard/api-keys.

Kifly MCP Integration Guide

Connect any MCP-compatible agent (Claude, Gemini, or custom) to Kifly's live product catalog using the Model Context Protocol over HTTP.

Endpoint

https://kifly.io/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 → 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.

Endpoint	URL
Authorization server metadata	`https://kifly.io/.well-known/oauth-authorization-server`
Dynamic client registration	`https://kifly.io/oauth/register`
Authorization	`https://kifly.io/oauth/authorize`
Token	`https://kifly.io/oauth/token`

PKCE S256 required. Refresh tokens rotate on each use (leak-containment chain).

Connecting from Google AI Studio (Gemini)

Open aistudio.google.com
In the left sidebar → Tools → Add tool → MCP Server
Enter the server URL: https://kifly.io/api/mcp

Under Headers, add:

Authorization: Bearer kfa_live_xxxxxxxxxxxxxxxx

Click Connect — Gemini will call tools/list and confirm the 9 available tools

Connecting from Claude Desktop (stdio)

For local stdio use, build the MCP package and add to claude_desktop_config.json:

{
  "mcpServers": {
    "kifly": {
      "command": "node",
      "args": ["/absolute/path/to/kifly-agent/kifly/packages/mcp/dist/cli.js"],
      "env": {
        "KIFLY_AGENT_KEY": "kfa_live_xxxxxxxxxxxxxxxx",
        "KIFLY_BASE_URL": "https://kifly.io"
      }
    }
  }
}

Required env vars: KIFLY_AGENT_KEY (seller API key) and KIFLY_BASE_URL (portal origin).

Available Tools (9)

Tool	Description
`get_seller`	Seller profile: location, storefront URL, `delivery_zones`, `delivery_fee_cents`, `catalog_size`. Call early to pre-screen whether the seller delivers to the buyer's area.
`get_buyer_profile`	Repeat buyer identity via `kfb_live_...` token — name, email, default shipping address for auto-fill.
`search_products`	Semantic vector search. Omit `q` to browse; pass `q` for ranked results. Multilingual.
`create_cart`	Create a new shopping cart. Returns `cart_id`.
`add_to_cart`	Add a variant by `variant_id` and `quantity`.
`set_shipping_address`	Required before `checkout`. Persist address, validate postal code against `delivery_zones`, return delivery-inclusive total.
`checkout`	Stripe Payment Link + `session_id`. Requires prior `set_shipping_address`. Optional `buyer_token` pre-fills email.
`order_status`	Poll checkout session — `pending`, `paid`, `shipped` (with tracking), or `failed`.
`submit_feedback`	Structured agent feedback to the Kifly team (fire-and-forget, 10/min per token).

Recommended purchase flow

get_seller (optional)
  → get_buyer_profile (optional, if buyer has kfb_live_ token)
  → search_products
  → create_cart
  → add_to_cart (repeat)
  → set_shipping_address
  → checkout
  → [buyer pays at payment_url]
  → order_status (poll until paid or shipped)

search_products

{
  "q": "leather wallet",
  "limit": 10
}

q is optional — omit to browse the most recent listings. Returns a JSON-LD ItemList with name, description, kifly:variantId, offers.price, and kifly:seller on each item.

set_shipping_address

{
  "cart_id": "…",
  "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 on failure the seller's delivery_zones so the agent can explain out-of-range delivery.

Rate Limits

Surface	Limit
`/api/mcp`	120 requests / 60 seconds per token
`/api/agent/*`	60 requests / 60 seconds per token
`/api/agent/feedback`	10 requests / 60 seconds per token

Responses include x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset headers. Breaches return 429 with retry-after.