Documentation

One endpoint speaks MCP, another speaks plain HTTP. Both need the same free API key.

Quickstart

Sign in with your email and create a key. It is shown once.
Paste the snippet for your client below.
Ask for something: “where is chicken breast cheapest near M4C 1B5?”

Customize → Connectors → Add custom connector

https://grocery-price-mcp.vercel.app/mcp?api_key=gpm_live_your_key_here

Works in Claude on the web, desktop and mobile. Claude can't send headers, so the key is part of this URL. Keep it private.

Authentication

Send your key one of three ways. The header forms are preferred; the query parameter exists for clients that cannot set headers, and it does end up in server logs and browser history, so treat a key used that way as lower-trust and rotate it if it leaks.

# preferred
curl -H "Authorization: Bearer gpm_live_..." "https://grocery-price-mcp.vercel.app/v1/compare?q=eggs"

# also accepted
curl -H "x-api-key: gpm_live_..." "https://grocery-price-mcp.vercel.app/v1/compare?q=eggs"

# last resort, for header-less clients
curl "https://grocery-price-mcp.vercel.app/v1/compare?q=eggs&api_key=gpm_live_..."

Every reply carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds).

MCP endpoint

Streamable HTTP, stateless, JSON replies. Point any MCP client at:

https://grocery-price-mcp.vercel.app/mcp

`search_groceries`	A city-aware shopping list: up to ten ingredients with real prices, product photos and retailer links. Supports Toronto, Edmonton, Calgary, Vancouver, Winnipeg, Montréal, Halifax and Saskatoon.
`compare_prices`	Where a product is cheapest across every store and flyer, ranked by unit price.
`cheapest_in_category`	The best in-stock offer for each common item in fruit or vegetables.
`store_search`	One store's live catalogue, in that store's own ranking.
`flyer_deals`	This week's flyer deals for a product, optionally at one merchant.
`list_stores`	Every source, the nearest Loblaw-family locations, and flyers near a postal code.
`tnt_specials`	T&T's current Price Drop and Multi-Save promotions.
`tnt_browse / tnt_categories`	Browse T&T by category id, and list the category tree.
`instacart_markup / instacart_check`	Which Toronto stores charge more on Instacart than in store.

Most tools take an optional postalCode; the default is downtown Toronto (M5V 2T6).

REST API

GET/v1/compare

Every matching offer across all sources, ranked by unit price.

params: q (required), postal, sources, strict, limit

GET/v1/category/{category}

Best in-stock offer per item for fruit or vegetables.

params: postal

GET/v1/stores/{store}/search

One store's own catalogue, unfiltered and in its own ranking.

params: q (required), postal, limit

GET/v1/flyers

Grocery flyers currently running near a postal code.

params: postal

GET/v1/sources

Source ids, coverage notes and available categories.

params: —

GET/health

Liveness. The only endpoint that needs no key.

params: —

Example request

curl -H "Authorization: Bearer gpm_live_your_key_here" \
  "https://grocery-price-mcp.vercel.app/v1/compare?q=2%25%20milk%204L&postal=M5V2T6&limit=5"

Trimmed response

{
  "query": "2% milk 4L",
  "postalCode": "M5V2T6",
  "basis": "perL",
  "offers": [
    {
      "store": "No Frills",
      "source": "pcx:nofrills",
      "kind": "store",
      "name": "2% Milk",
      "size": "4 L",
      "price": 5.79,
      "priceUnit": "each",
      "onSale": false,
      "unit": { "perL": 1.45 },
      "inStock": true,
      "location": "Toronto — Dufferin",
      "image": "https://assets.shop.loblaws.ca/...",
      "url": "https://www.nofrills.ca/2-milk/p/20039684_EA"
    }
  ],
  "stores": [
    { "store": "No Frills", "source": "pcx:nofrills", "matches": 3 },
    { "store": "Metro", "source": "flipp", "matches": 1 }
  ]
}

Sources and coverage

Prices come from public retailer listings and weekly flyers. Live searches are cached for about 15 minutes, while store directories and flyers are cached longer. A source failing never prevents the others from returning results.