Findcheap MCP server

The Findcheap MCP server lets an AI assistant find where a product is sold for less. It offers the capabilities of the Findcheap API as four tools that any MCP client (Claude, Claude Code, Cursor and others) can call in a conversation:

  1. find_cheaper - takes a product page URL as input and searches the internet to find where the product is available for a lower price.
  2. read_product_page - takes a product page URL as input and returns structured product data from the page.
  3. resolve_listing - a utility tool that turns a result’s resolve_id into the merchant’s link and name.
  4. find_cheaper_feedback - records how a search went. The first report on a search gives 1 credit back.
Server URL (Streamable HTTP)
https://mcp.findcheap.ai/mcp

Each tool answers exactly what the corresponding API endpoint answers. This page covers how to connect and what each tool takes; every field of the answers is documented in the API reference. The same reference says how the API and these tools are versioned and lists every change, under Versioning and changes.

The examples on this page use our sample product page, https://findcheap.ai/sample-product: a copy of a real product page that does not change. Any product page’s address works the same way.

Connect

Two ways in, the same account behind both: sign in with your Findcheap account from ChatGPT, Claude.ai, Cursor or any other app that can sign in, or give a developer tool your API key.

ChatGPT: sign in

Findcheap is a plugin in ChatGPT. Open its page there and add it:

Then sign in: ChatGPT sends you to findcheap.ai, you sign in (or create an account, free) and allow ChatGPT to use it. From then on ChatGPT searches on your plan’s credits.

Claude.ai: sign in

In Claude (web, desktop or mobile) open Customize, then Connectors, and add a custom connector: name it Findcheap, enter the server URL below and continue. Under OAuth client choose “Use your own OAuth client” and paste this client ID (there is no secret):

Server URL (Streamable HTTP)
https://mcp.findcheap.ai/mcp
OAuth client ID for Claude.ai
d125ba2b-831c-403b-a456-a1141ef32231

Add it, then sign in: Claude sends you to findcheap.ai, you sign in (or create an account, free) and allow Claude to use it. From then on Claude searches on your plan’s credits.

Cursor: sign in

Press the button and Cursor asks to add the server:

Or add it by hand:

// .cursor/mcp.json (or the global ~/.cursor/mcp.json)
{
  "mcpServers": {
    "findcheap": {
      "url": "https://mcp.findcheap.ai/mcp",
      "auth": { "CLIENT_ID": "3e10d062-c366-4f8c-a85d-b87395178793" }
    }
  }
}

Then sign in: Cursor sends you to findcheap.ai, you sign in (or create an account, free) and allow Cursor to use it. From then on Cursor searches on your plan’s credits.

Any other app: sign in

Any app that can sign in to an MCP server connects with the server URL alone, with no API key. Add the URL in the app:

claude mcp add --transport http findcheap https://mcp.findcheap.ai/mcp
claude mcp login findcheap

Then sign in: the app sends you to findcheap.ai, you sign in (or create an account, free) and allow the app to use it. From then on the app searches on your plan’s credits.

Developer tools: the API key

Claude Code, Cursor, the Claude API and your own code take the key the API uses (create one in your dashboard, free). It travels in the Authorization header of every request.

claude mcp add --transport http findcheap https://mcp.findcheap.ai/mcp \
  --header "Authorization: Bearer fc_live_..."

Any other MCP client connects the same way: the server URL above, Streamable HTTP, and the Authorization header.

Authentication

Every request carries either your API key or the sign-in token an app holds for you:

Authorization: Bearer fc_live_...

A request without a valid key or token is answered 401 before anything else happens, which a client reports as a failed connection; the answer also points a client at the server’s OAuth metadata, so a client that can sign in knows where to. A key is valid for the API and the MCP server alike, a sign-in for the MCP server, and all of them draw on the same credits and the same rate limits: a find_cheaper call costs 10 credits, a read_product_page call 1, a resolve_listing call 1 and a find_cheaper_feedback call nothing (the first report on a search gives 1 credit back); a call that fails costs nothing, except a find_cheaper call that stops because the page is not a product page or the used search is refused, which is billed as a page read, 1 credit.

The sign-in is standard OAuth 2.1: the server publishes its metadata at /.well-known/oauth-protected-resource/mcp, the authorization server is Findcheap’s own, an app registers itself (OAuth dynamic client registration, at the registration_endpoint in the authorization server’s metadata), and PKCE is required. An app’s return address is https, or http on the person’s own computer (localhost, on any port).

find_cheaper

TOOLfind_cheaper

Takes a product page URL as input and searches the internet for where the product is available for a lower price. It is the Search endpoint as a tool: the agent reads the product page, then searches the marketplaces of the shopper’s market. Results are sorted into two arrays, each containing up to 10 results:

  • same_product - listings that match the original product. Sorted by cheapest first.
  • similar_products - acceptable equivalents of the original product. Sorted by cheapest first.

It has a maximum budget of 60 seconds, but usually completes much sooner. While it runs, the server sends progress notifications (reading the page, searching, comparing) to clients that display them.

Two ways it gets used:

  • User-initiated. A shopper pastes a product link into their assistant and asks for it cheaper; the assistant calls find_cheaper and answers with the retailers, prices and links.
  • Agent-initiated. An agent working on a task the user gave it, “buy me a soccer ball”, finds a candidate ball on Amazon and calls find_cheaper on that page to see whether the same ball, or an equivalent, is sold for less elsewhere before recommending or buying it.

In both, there is nothing to build: the assistant decides when to call the tool from its description.

Parameters

url
string · required

The product page’s address (https), as the shopper sees it.

market
string

The shopper’s market, the country they are buying in (see Markets). If omitted, the market is inferred from the URL; otherwise, it defaults to US.

marketplaces
string[]

Which marketplaces to search. Only marketplaces available in the shopper’s market count. If omitted, the agent chooses for the product. Accepted values: "amazon", "walmart", "ebay", "aliexpress", "shein", "flipkart", "other_sites".

condition
"new" | "used"

Defaults to "new". If set to "used", the agent searches for where the product can be bought secondhand. This search mode is not available in India, and is refused for grocery and consumable products.

max_results
integer

How many listings at most in each list, 1 to 10; 10 when omitted. Ask for fewer when only the cheapest few matter. The search is the same, and so are the credits.

Result

The Search endpoint’s answer, as JSON, in this order: search (what was searched: the address, the market, the condition, the cap), product, product_name, about_lists (what the two lists hold for this search), same_product, similar_products, page_is_cheapest and next_steps (what can be done next, each with the call that does it). The endpoint’s request_id and credits_used are not in the answer; they are in the result’s _meta (see The call’s id and cost, below). Every field, and the structure of a card, is documented under Search in the API reference. A card whose url is null carries a resolve_id for resolve_listing. Each tool also publishes its answer’s schema in the tool listing (outputSchema: every field, its type and whether it can be null), so a client can check an answer before it shows it.

Example

The call the assistant makes, and the answer trimmed to one card per list:

Call
find_cheaper({ "url": "https://findcheap.ai/sample-product" })
Answer
{
  "search": {
    "url": "https://findcheap.ai/sample-product",
    "market": "US",
    "condition": "new",
    "max_results": 10
  },
  "product": {
    "title": "Nike Dunk High By You Custom Men's Shoes",
    "price": 160.0,
    "currency": "USD",
    "brand": "Nike",
    "url": "https://findcheap.ai/sample-product",
    "market": "US",
    "image": "https://findcheap.ai/demo-photos/nike-dunk-high-by-you.png",
    "in_stock": true,
    "retailer": null,
    "coupon": null,
    "promo_code": null,
    "shipping_cost": null,
    "returns_accepted": null,
    "return_days": null,
    "return_shipping_paid_by": null,
    "pack_count": null
  },
  "product_name": "Nike shoes",
  "about_lists": "same_product holds listings from the original product's brand that look the same or similar. similar_products holds look-alikes from any brand.",
  "same_product": [
    {
      "title": "Nike Dunk Hi Retro Blue/White Leather Men’s US 11 Sneaker DD1399-102",
      "price": 69.0,
      "currency": "USD",
      "retailer": "eBay",
      "url": "https://www.ebay.com/itm/178217128667",
      "resolve_id": null,
      "image": "https://i.ebayimg.com/images/g/VGwAAeSwwNtqLLg0/s-l500.jpg",
      "over_page_price": false,
      "rating": 100.0,
      "coupon": null,
      "promo_code": null,
      "price_before_discount": null,
      "discount_type": null,
      "discount_value": null,
      "shipping_cost": null
    }
  ],
  "similar_products": [
    {
      "title": "Nike By You Dunk High Sail Black FV5511 900 Men's Size 10.5",
      "price": 59.99,
      "currency": "USD",
      "retailer": "eBay",
      "url": "https://www.ebay.com/itm/354741245174",
      "resolve_id": null,
      "image": "https://i.ebayimg.com/images/g/BIAAAOSwl2RkRuKP/s-l500.jpg",
      "rating": 100.0,
      "coupon": null,
      "promo_code": null,
      "price_before_discount": null,
      "discount_type": null,
      "discount_value": null,
      "shipping_cost": null,
      "over_page_price": false
    }
  ],
  "page_is_cheapest": false,
  "next_steps": [
    {
      "label": "Find pre-owned",
      "tool": "find_cheaper",
      "arguments": { "url": "https://findcheap.ai/sample-product", "market": "US", "condition": "used" },
      "choose": null
    },
    {
      "label": "Filter stores",
      "tool": "find_cheaper",
      "arguments": { "url": "https://findcheap.ai/sample-product", "market": "US", "condition": "new" },
      "choose": { "marketplaces": ["amazon", "walmart", "ebay", "aliexpress", "shein", "other_sites"] }
    }
  ]
}

read_product_page

TOOLread_product_page

Takes a product page URL as input and returns structured product data from the page, without searching. It is the Extract endpoint as a tool. It answers within 30 seconds, and has a median response time of 4 seconds.

Two ways it gets used:

  • User-initiated. A shopper pastes a product link into their assistant and asks what it sells, what it costs or whether it is in stock; the assistant calls read_product_page and answers from the page’s data.
  • Agent-initiated. An agent working on a task the user gave it, “compare these three monitors”, calls read_product_page on each page to get the title, price, brand and stock it needs before comparing them.

In both, it answers what the page says and nothing more; find_cheaper is the tool that searches.

Parameters

url
string · required

The product page’s address (https).

market
string

The market to read the page from (see Markets). If omitted, the market is inferred from the URL; otherwise, it defaults to US.

Result

The Extract endpoint’s answer: is_product_page, title, image, price, currency, brand, in_stock, retailer, coupon, promo_code, shipping_cost, returns_accepted, return_days, return_shipping_paid_by, url, market, reason and next_steps (what can be done next for this product: the search for it, with the call that does it). Every field is documented under Extract in the API reference.

Example

Call
read_product_page({ "url": "https://findcheap.ai/sample-product" })
Answer
{
  "is_product_page": true,
  "url": "https://findcheap.ai/sample-product",
  "market": "US",
  "title": "Nike Dunk High By You Custom Men's Shoes",
  "image": "https://findcheap.ai/demo-photos/nike-dunk-high-by-you.png",
  "price": 160.0,
  "currency": "USD",
  "brand": "Nike",
  "in_stock": true,
  "retailer": null,
  "coupon": null,
  "promo_code": null,
  "shipping_cost": null,
  "returns_accepted": null,
  "return_days": null,
  "return_shipping_paid_by": null,
  "reason": null,
  "next_steps": [
    {
      "label": "Find this cheaper", "tool": "find_cheaper",
      "arguments": { "url": "https://findcheap.ai/sample-product", "market": "US" },
      "choose": null
    }
  ]
}

resolve_listing

TOOLresolve_listing

For some results, find_cheaper only returns top-level data, to maximize search efficiency. These results carry a resolve_id instead of a url. Calling resolve_listing with a resolve_id returns a direct link to the corresponding product on the merchant’s website and the merchant’s name. It is the Resolve endpoint as a tool.

An id is valid for up to two hours after the search that produced it. In rare cases, it may expire sooner, so it is advised to resolve any desired ids shortly after the search has completed.

Parameters

resolve_id
string · required

The card’s resolve_id.

Result

FieldTypeMeaning
resolvedbooleantrue when url holds the retailer's link.
urlstring | nullThe product’s link on the merchant’s website, tracking parameters stripped. null when not resolved. On the Free plan it may be an affiliate link; see Links.
retailerstring | nullThe merchant's name, e.g. "B&H Photo". null when not resolved.

An id that is unknown, expired, or could not be resolved answers { "resolved": false, "url": null, "retailer": null }; it is never an error.

Example

Call
resolve_listing({ "resolve_id": "7c1f0e2b4d9a4f3e8b6a2c5d9e1f0a3b" })
Answer
{
  "resolved": true,
  "url": "https://www.walmart.com/ip/Soundcore-Q20i/...",
  "retailer": "Walmart"
}

find_cheaper_feedback

TOOLfind_cheaper_feedback

Records how a find_cheaper search went: which cards were useful, which do not belong in their list, a cheaper listing found elsewhere, what was missing. It is the Feedback endpoint as a tool, and the server’s one write tool: it records a report with Findcheap and changes nothing else. A call costs nothing, and the first report on a search gives 1 credit back.

The tool names its search by url, the product page address the search was run on, because an assistant is shown no call id. The account’s latest search of that address in the last 20 minutes is the one meant.

The limits are the endpoint’s: one report per search, within 20 minutes of it; 1 credit back for the first report on a search, up to 100 credits a day per account, counted on the UTC day; and an account can switch feedback off in its dashboard, under Account.

The tool’s description says what it records. It does not tell an assistant to send a report. To have an assistant send one after each search, give it the Feedback section of the agent skill, /skills/findcheap/SKILL.md, or call the tool from your own code.

Parameters

url
string · required

The product page address the search was run on: the url you gave find_cheaper.

rating
"good" | "partial" | "bad" · required

How the search went: "good", "partial" or "bad".

useful_cards
object[]

The cards you showed or recommended, each named by its list and its position in it.

Each entry is an object with list ("same_product" or "similar_products") and position (the card’s place in that list, counting from 1).

wrong_cards
object[]

Cards that do not belong in their list, each named by its list and its position in it, with a reason.

Each entry is an object with list, position and reason: "different_product" (it is not the product the page sells), "not_equivalent" (it is not an acceptable equivalent), "price_differs" (the listing’s price is not the card’s), "unavailable" (the listing is gone or out of stock) or "other".

cheaper_elsewhere
object[]

Cheaper listings you found that the answer did not have, each with its address and its price.

Each entry is an object with url (the cheaper listing’s address) and price (its price, in the market’s currency; null when you do not know it).

missing
string[]

What you expected and did not get, one short sentence each.

goal
string

What the shopper was trying to do, in one sentence. Nothing personal about the shopper.

note
string

Anything else worth knowing about this search, short.

Send the rating and at least one other field. Each list holds at most 20 entries. Text longer than its limit is cut, not refused: goal and each missing sentence at 300 characters, note at 1,000.

Result

The Feedback endpoint’s answer: recorded, already_reported, credits_refunded, refunded_today, daily_refund_cap and daily_cap_reached. Every field is documented under Feedback in the API reference.

Description

What the tool tells an assistant about itself, word for word:

Record how a find_cheaper search went, so Findcheap can improve its results. Give `url`, the product page address the search was run on, and `rating` (`good`, `partial` or `bad`), with at least one of: `useful_cards` (the cards you showed or recommended), `wrong_cards` (cards that do not belong in their list, each with a `reason`), `cheaper_elsewhere` (a cheaper listing you found that the answer did not have), `missing` (what you expected and did not get), `goal` (what the shopper was trying to do, in one sentence) and `note`. A card is named by its list (`same_product` or `similar_products`) and its position in that list, counting from 1. Keep it short: no page contents, and nothing personal about the shopper. A report counts for a search made in the last 20 minutes, once per search; a second report on the same search changes nothing. The first report on a search gives 1 credit back, up to 100 credits a day. Answers `recorded`, `already_reported`, `credits_refunded` and `daily_cap_reached`.

Example

Call
find_cheaper_feedback({
  "url": "https://findcheap.ai/sample-product",
  "rating": "partial",
  "useful_cards": [{ "list": "same_product", "position": 1 }],
  "wrong_cards": [{ "list": "similar_products", "position": 1, "reason": "not_equivalent" }],
  "goal": "The same shoes for under 100 dollars."
})
Answer
{
  "recorded": true,
  "already_reported": false,
  "credits_refunded": 1,
  "refunded_today": 1,
  "daily_refund_cap": 100,
  "daily_cap_reached": false
}

The call’s id and cost

Every result carries two values in its _meta, the part of a tool result that a client application can read and an assistant’s model is not shown:

KeyTypeMeaning
ai.findcheap/request_idstringThe call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call.
ai.findcheap/credits_usednumberWhat the call cost the account: 10 for a search, 1 for a page read, 1 for a link that was resolved, 0 for one that was not, 0 for feedback.
ai.findcheap/errorstringOn a tool error only: the error's type, e.g. not_searchable (see Errors below).
ai.findcheap/searched_atstringOn a find_cheaper answer only: when the search was made, in UTC (2026-11-14T18:05:09Z). The prices and links are those of that moment.

A tool error carries the first two as well: the cost is 1 for not_searchable and refused (the page was read before the search stopped) and 0 for every other error, and the id is absent only when the call was refused before it began (unauthorized, rate_limited, account_suspended, account_service_unavailable). The dashboard lists every recorded call with its id.

Errors

A tool call that cannot be served returns a tool error. Its text is one plain sentence the assistant can read out to the person it is helping, e.g. This is not a product page, so there is nothing to search for. Send the address of an individual product page to search. The sentence names no error type and no cost. The type is in the result’s _meta under ai.findcheap/error. The types are the API’s (see Errors in the API reference); the API’s own messages are worded for developers and differ from these sentences:

TypeToolWhen
invalid_urlallThe url is not a web address we can fetch; the sentence says why.
unknown_marketallThe market is not one the agent serves.
invalid_requestallA parameter has the wrong shape, e.g. an unknown marketplace name.
not_searchablefind_cheaperThe page is not a readable product page; the sentence says why.
refusedfind_cheaperA used-condition search for a grocery or consumable product, or for a product with no determinable brand.
unreachablefind_cheaper, read_product_pageThe page could not be fetched right now; try again later.
timeoutfind_cheaper, read_product_pageThe page was reached but could not be read within 30 seconds, or the search did not finish within 60 seconds; try again.
rate_limitedallThe account is over one of its per-minute limits; the sentence says how long to wait.
credits_exhaustedallThe account has used its plan's credits for the period; the sentence names the plan and the reset date (monthly from the sign-up date on the free plan, the renewal on a paid one).
unauthorizedallThe key is missing or wrong (also a 401 when the client connects).
account_suspendedallThe account is suspended; the sentence says whom to write to.
account_service_unavailableallThe key could not be checked right now; try again in a moment.
search_not_foundfind_cheaper_feedbackThe account made no search of that address in the last 20 minutes; no feedback is recorded.
feedback_offfind_cheaper_feedbackFeedback is switched off for the account.

Rate limits

Limits are per account and per minute (the plans are on the developers page). An account has one budget: a find_cheaper call counts as a Search request, read_product_page as an Extract request, resolve_listing as a Resolve request and find_cheaper_feedback as a Feedback request, whether made through the MCP server or the API.

PlanCredits a monthSearches/minOther requests/min
Free1,000 (100 searches)530
Developer5,000 (500 searches)20100
Startup40,000 (4,000 searches)150300
Growth250,000 (25,000 searches)1,0001,000
EnterpriseCustomCustomCustom