# AI agents & MCP

Kibanda works with AI assistants in both directions:

- **The shop owner's assistant runs the shop** — "what sold this week?", "restock unga to 40", "cancel order 128", "send Achieng a link for two trays of eggs". This is the **merchant MCP server**.
- **A customer's assistant shops** — finds products and hands the person a WhatsApp link to confirm and pay. This is each shop's **shopper MCP server** and `llms.txt`.

Payment always happens in WhatsApp, confirmed by the person. Agents never see card or M-Pesa details.

## Merchant MCP server

```
URL:   https://api.kibanda.africa/mcp
Auth:  Authorization: Bearer kb_live_…   (an API key from Dashboard → Developers)
```

Transport: Streamable HTTP (JSON responses), MCP protocol versions `2025-11-25`, `2025-06-18` and `2025-03-26`.

**Claude Code:**

```bash
claude mcp add --transport http kibanda https://api.kibanda.africa/mcp \
  --header "Authorization: Bearer $KIBANDA_KEY"
```

**Cursor / any client with a JSON config:**

```json
{ "mcpServers": { "kibanda": { "url": "https://api.kibanda.africa/mcp", "headers": { "Authorization": "Bearer kb_live_…" } } } }
```

| Tool | |
|---|---|
| `get_shop` | Name, WhatsApp number, delivery and pickup settings. |
| `sales_summary` | Sales, orders, top products, delivery performance, repeat customers over N days. |
| `list_orders` | Recent orders, filter by status or customer. |
| `get_order` | One order by id or by the number customers know (#128), with its history. |
| `cancel_order` | Cancel an unpaid order with a reason the customer sees. |
| `list_products` | Catalog with prices, stock and availability. |
| `add_product`, `update_product` | Prices in shillings, stock, hide/show. |
| `find_customer`, `get_customer`, `update_customer` | Look up by phone/email/tag; notes and tags. |
| `create_checkout_link` | A WhatsApp link with a ready cart, to send a customer. |
| `recent_activity` | The latest events (orders, payments, deliveries, new customers, abandoned carts). |

Every tool goes through the same API as everything else, so it obeys the same rules and fires the same webhooks.

## Shopper MCP server (one per shop)

```
URL:   https://api.kibanda.africa/s/<shop-slug>/mcp
Auth:  none (public catalog only)
```

| Tool | |
|---|---|
| `shop_info` | Delivery fees, pickup, payment methods. |
| `search_products` | Products and prices (KES). |
| `get_product` | One product by id or share code. |
| `create_checkout` | Returns a WhatsApp `url` with the cart ready; the person opens it to confirm and pay. |

## llms.txt

- These docs: [`/llms.txt`](https://kibanda.africa/llms.txt) and [`/llms-full.txt`](https://kibanda.africa/llms-full.txt); any page as Markdown with `.md`.
- Each shop: `https://api.kibanda.africa/s/<shop-slug>/llms.txt` — what it sells, prices, delivery, and how an agent places an order. Also `/s/<shop-slug>/products.json`.

## Guidance for agent builders

- Quote prices from the tools, not memory; stock changes.
- Send the person the checkout `url` and tell them they'll confirm and pay in WhatsApp.
- For the merchant server, confirm before cancelling orders or changing prices.