Rudia for AI assistants

Connect ChatGPT, Claude, Gemini or any AI agent to Rudia: search local Kenyan shops and products, check delivery to an area and hand the buyer a ready-to-pay M-Pesa basket. MCP server and public JSON API.

Connect

MCP server (Streamable HTTP, no sign-in): https://rudia.co/api/mcp
JSON API: https://rudia.co/api/v1
OpenAPI document: https://rudia.co/api/v1/openapi.json
Summary for language models: https://rudia.co/llms.txt

Claude: Settings → Connectors → Add custom connector, and paste the MCP server URL.
ChatGPT: add it as a connector or app with the MCP server URL (developer mode where your plan requires it).
Other agents: point any MCP client at the URL, or call the JSON API described by the OpenAPI document.

How an order works

1Search. search_products takes the area as the buyer said it and finds items from shops that deliver there, nearest first, with KES prices and stock. The result's area shows which place it matched; if that looks wrong, resolve_area lists candidates to pass back. search_stores lists the shops.
2Compare. get_product shows options and subscription prices; check_delivery confirms the shop delivers to the area and on which days.
3Hand off. create_checkout_link returns a link to Rudia's basket with the items already in it, plus an estimated total. It is a one-time order; for a repeat delivery, send the product's link so the buyer can choose Subscribe there.
4Pay. The buyer opens the link, signs in with their phone number, picks the address and delivery day, and pays with M-Pesa. Nothing is charged before that.

Tools

resolve_area

Turns the buyer's place (estate, road, town) into candidate places, Rudia's own delivery areas first. Use it when a place name is ambiguous, then pass the chosen name as area to the other tools.

GET /api/v1/areas

Field	Type	Description
textrequired	string	Free text for the place, as the buyer said it.

search_products

Finds products from shops that deliver to the buyer's area, nearest shops first, with KES prices, subscription prices, stock and a product link. The area is required because shops only deliver locally. Filters apply to each nearby shop's top items; use get_store with query to search one shop's full range.

GET /api/v1/products

Field	Type	Description
query	string	One or two product words, e.g. "water", "diapers", "gas". Omit to browse.
arearequired	string	Where the buyer wants delivery: an estate, road or town in Kenya, e.g. "Kilimani" or "Ruaka".
category	string	A category slug from list_categories, e.g. "groceries", "baby", "health-beauty".
max_price_kes	integer	Highest price per unit in KES. Applied to each nearby shop's top items, not its whole range.
subscription_only	boolean	Only products that can be delivered on a repeat schedule. Applied to each nearby shop's top items.
limit	integer	How many results, 1-20, default 10.

search_stores

Finds shops, optionally only those delivering to an area or in a category, with delivery days and recent deliveries.

GET /api/v1/stores

Field	Type	Description
area	string	Only stores that deliver here. Strongly recommended.
category	string	A category slug from list_categories, e.g. "groceries", "baby", "health-beauty".
query	string	Part of a store name or category.
limit	integer	How many results, 1-20, default 10.

get_store

A store's delivery areas, delivery days and time windows, order cutoff, minimum order, pickup option and up to 50 of its products (products_total says how many there are; pass query to find a product by name in this shop). The delivery fee is estimated by create_checkout_link and confirmed at checkout.

GET /api/v1/stores/{store_slug}

Field	Type	Description
store_slugrequired	string	The store's slug, from a search result.
query	string	Filter this store's products by name, to find one in a large shop.

get_product

Full detail for one product: description, options (variants) with their own ids and prices, stock, subscription price and frequencies.

GET /api/v1/stores/{store_slug}/products/{product_slug}

Field	Type	Description
store_slugrequired	string	The store's slug.
product_slugrequired	string	The product's slug, from a search result.

check_delivery

Whether a store delivers to the buyer's area, with delivery days and cutoff. The delivery fee is estimated by create_checkout_link and confirmed at checkout.

GET /api/v1/delivery-check

Field	Type	Description
store_slugrequired	string	The store's slug.
arearequired	string	Where the buyer wants delivery: an estate, road or town in Kenya, e.g. "Kilimani" or "Ruaka".

create_checkout_link

Builds a link to Rudia's basket with these items already in it (up to 20 lines across up to 10 shops) and returns per-shop prices and an estimated total. Products with options need a variant_id from get_product. Nothing is charged: the buyer opens the link, signs in with their phone and pays with M-Pesa. The checkout link is a one-time order at one-time prices. For a repeat delivery, give the buyer the product's url instead; they choose Subscribe and a schedule there.

POST /api/v1/checkout-links

Field	Type	Description
linesrequired	array	Items for the basket: [{ product_id, variant_id?, quantity }], up to 20 lines across up to 10 shops. Repeated lines for the same item are added together.

Example

curl "https://rudia.co/api/v1/products?query=water&area=Kilimani&limit=5"

curl -X POST "https://rudia.co/api/v1/checkout-links" \
  -H "content-type: application/json" \
  -d '{"lines":[{"product_id":"<product_id>","quantity":2}]}'

Good to know

Prices are whole Kenyan shillings and are the merchant's own prices. The delivery fee and a service fee are added at checkout, where the final total is confirmed.
Payment is M-Pesa on Rudia. No tool takes payment or places an order by itself.
Limits: 120 reads and 60 checkout links per minute per caller. A 429 response carries Retry-After.
Only quote what the tools return. Shops' own descriptions are the shops' words, not Rudia's.
Links carry src=llm and utm tags so we can see which assistants send buyers.