kams
Developer docs

Shop Kams stalls from any AI agent

Every Kams stall is a live Model Context Protocol server. Connect Claude, ChatGPT, Cursor or your own agent, and it can search small sellers' goods and buy them with a real PayPal Orders v2 checkout. The buyer always approves the payment in PayPal.

MCP endpoint (Streamable HTTP, no auth needed to browse)

https://www.usekams.xyz/mcp

One stall only: https://www.usekams.xyz/mcp/<stall-slug>, e.g. https://www.usekams.xyz/mcp/mama-tolu-fabrics-beads

Claude Code

Add Kams as a remote MCP server, then ask Claude to shop.

claude mcp add --transport http kams https://www.usekams.xyz/mcp

Then try: "Find me a blue beaded necklace under $15 on Kams and buy it."

Claude Desktop and claude.ai

Settings → Connectors → Add custom connector. Name it Kams and paste the endpoint URL above. Or, for clients that read a JSON config:

{
  "mcpServers": {
    "kams": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.usekams.xyz/mcp"]
    }
  }
}

Cursor and other MCP clients

Add a remote server in .cursor/mcp.json (or your client's equivalent):

{
  "mcpServers": {
    "kams": { "url": "https://www.usekams.xyz/mcp" }
  }
}

Tools

list_stores

— (only on /mcp, the all-stalls endpoint)

Lists every live Kams stall with its name, location, tagline and product count.

search_products

query, max_price?, category?, limit?

Finds products by keywords and budget. Returns titles, USD prices, tags and agent-facing descriptions.

get_product

product_id

Full details for one product, written for AI agents to read.

create_order

items[{product_id, quantity}], note?

Creates an itemized PayPal Orders v2 checkout (sandbox). Returns a checkout_url the human buyer opens to approve in PayPal. Prices always come from the catalogue.

get_order_status

order_id

Checks the order. Once the buyer has approved, Kams captures the payment and returns paid=true with the PayPal capture ID.

How a purchase works

  1. The agent calls search_products and picks an item.
  2. It calls create_order with product IDs and quantities only. Kams prices the order from the catalogue and creates a PayPal Orders v2 checkout.
  3. The agent gives the human the checkout_url. They log in and approve in PayPal.
  4. The agent calls get_order_status. Kams captures the payment and returns paid: true. Agents should never say an order is paid before this.

Everything runs on the PayPal sandbox: no real money moves. Use a PayPal sandbox personal account to approve (the judges' test login is in the README).

Raw MCP request

The endpoint speaks JSON-RPC over Streamable HTTP. List the tools with curl:

curl -s https://www.usekams.xyz/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'