MCP tools reference

The CouponLlama MCP server at https://couponllama.com/mcp exposes 5 tools. All of them are free to call without a key. Results come back as JSON text and as structured content, with a link to the store page for every code so an assistant can cite it.

find_promo_codes

Find promo codes for a store. Live promo codes for one online store, best offer first. Accepts the store's name, its website (“store.com”) or any URL on it. Each code comes with what it gives, its conditions, how many shoppers said it worked and when it last worked. When no store matches, it says so and suggests close matches instead of guessing.

Read-only. Example request: “I'm about to check out at huegahouse.com. Is there a promo code?”

Parameter	Type	Description
`store`	string	Store name, domain or any URL on the store's site, for example “Huega House”, “huegahouse.com” or a link to a product page.

Response for {"store":"Bone and Grey Bridal"} (live, shortened)

{
  "found": true,
  "store": {
    "name": "Bone and Grey Bridal",
    "store_page": "https://couponllama.com/stores/bone-and-grey-bridal",
    "shop_url": "https://boneandgrey.com/?ref=welcome",
    "category": "fashion",
    "live_codes": 2
  },
  "codes": [
    {
      "code_id": "j571qbm25v6trvd2qdnen16d0x8hzdw0",
      "code": "FALLWEDDING",
      "offer": "12% off",
      "summary": "12% off storewide",
      "applies_to": "Storewide",
      "minimum_spend_usd": null,
      "ends": null,
      "shoppers_said_worked": 202,
      "shoppers_said_failed": 11,
      "last_worked": null,
      "added": "2024-09-17"
    },
    {
      "code_id": "j579nqt616wc76r66ch4wdwjzh8j170a",
      "code": "FIRSTLOOK",
      "offer": "10% off",
      "summary": "10% off 10% off your first order",
      "applies_to": "10% off your first order",
      "minimum_spend_usd": null,
      "ends": null,
      "shoppers_said_worked": 0,
      "shoppers_said_failed": 0,
      "last_worked": null,
      "added": "2026-11-11"
    }
  ],
  "other_matches": [],
  "how_to_use": "Enter the code in the store's promo or discount code box at checkout. Report the outcome with report_code_result."
}

search_stores

Search stores. Stores CouponLlama covers that match a name or a category, with how many live codes each has and its best offer. Use it to browse (“which pet stores have codes?”) or when the user isn't sure of a store's exact name.

Read-only. Example request: “Find me a coupon for a pet supply store.”

Parameter	Type	Description
`query` (optional)	string	Part of a store's name, or words about what it sells.
`category` (optional)	string	A category slug from list_categories, such as “pets” or “home-garden”.
`with_codes_only` (optional)	boolean	Leave out stores with no live code. Defaults to true.
`limit` (optional)	number	How many stores to return, 1 to 50. Defaults to 20.

latest_promo_codes

Latest promo codes. The newest live codes across every store, optionally within one category. Good for “any new deals on…” questions.

Read-only. Example request: “Any new beauty promo codes this week?”

Parameter	Type	Description
`category` (optional)	string	A category slug from list_categories.
`limit` (optional)	number	How many codes to return, 1 to 50. Defaults to 20.

report_code_result

Report whether a code worked. Tell CouponLlama whether a code worked at checkout. The report joins the shopper vote tally, so the next person (or agent) knows which codes to trust. Call it once per code you tried.

Writes one vote; repeating it from the same caller changes nothing. Example request: “That code worked, thanks!”

Parameter	Type	Description
`code_id`	string	The id of the code, as returned by find_promo_codes.
`worked`	boolean	true if the store accepted the code, false if it was rejected.

Server instructions

The server sends these to the assistant when it connects, so it knows when to reach for a tool.

instructions

CouponLlama lists promo codes and coupon codes for online stores. Every code is added by hand and rated by shoppers who tried it.

Use find_promo_codes whenever the user is about to buy from an online store, asks for a discount, coupon or promo code, or is at a checkout. Pass the store's name, website or a product URL. The best offer comes first.

- Only offer codes this server returns. If it finds no store or no live code, say so; never make a code up.
- Pass on the conditions that come with a code (minimum spend, end date, what it covers) and the shopper vote tally.
- Link the store_page so the user can check the code and see newer ones.
- After the user (or you, at a checkout) has tried a code, call report_code_result with whether it worked. Those reports rate the code for the next shopper.

Protocol details

Transport: Streamable HTTP at https://couponllama.com/mcp. Stateless, so there is no session to keep alive.
Protocol revisions: 2026-07-28, and the 2025 revisions for older clients.
Authentication: none. Cross-origin requests are allowed, so browser-based clients work too.
Server name: couponllama. Discovery card at /.well-known/mcp/server-card.json.
Data freshness: the same catalog as the website, refreshed at most every five minutes. Codes leave the results on their end date.

Setting it up in a particular app? See the setup guides.