GroceryPulse Canada

npx add-mcp 'https://grocerypulse.ca/api/shopper/mcp'

Plan an order from the shopper’s own list.

When a shopper wants to buy groceries online, an assistant calls plan_grocery_order first (MCP), or POST /api/shopper/plan. It sends the list exactly as written, in English or French, with a covered city or the first three characters of a postal code inside one, and optionally the stores the shopper would use. No catalogue IDs are needed.

1. Every line, accounted for

   Each line comes back exact (with the quantity read from the line, flagged when assumed), closest (a different size, variant or brand: never priced, and the assistant should ask before switching), duplicate or not_tracked. A line over 120 characters is kept as not_tracked with reason: "line_too_long". Nothing is dropped and nothing unknown is guessed.

2. Store totals and an honest answer

   Store totals carry coverage and price dates. A cheapest store is named only under the same rule as compare_grocery_list: every compared item priced at two or more chains, with a clear lead. Pack items (toilet paper, paper towels, tea, garbage bags, bottled water) are compared per unit. When the only obstacle is a pack item whose count no store’s listing gives, the status lowest_for_compared_items names the cheapest store for the other lines and lists those items apart, in no total. Otherwise recommendation.explanation says why.

3. Links to each store’s own pages

   The recommended store and the next alternatives get per-item prices, dates and links to the store’s product page (when GroceryPulse recorded the priced product) or its search. No tracking or affiliate parameters. When an item carries a pack, its price is a standard amount at that store’s per-unit price and the link opens the store’s actual pack (count and shelf price given): the assistant should ask how many packs to buy.

4. Notes that come with every plan

   interpretation states what the result covers: totals add up only exact, priced lines; closest lines are unpriced and not chosen by the shopper; the result is not an order, a cart or a payment; and the store sets the final price. The assistant should show the comparison first, ask before substituting, add items to a cart only in the shopper’s own browser with their consent, and never check out or pay.

A plan request

POST /api/shopper/plan with Content-Type: application/json

{
  "list": "4L milk\n2 dozen eggs\nbananas\n3 lbs lean ground beef\nPC peanut butter",
  "postalCode": "K1P",
  "stores": ["No Frills", "Loblaws", "FreshCo"]
}

Limits

Up to 60 lines and 50 distinct tracked items. A postal code outside the covered city areas is refused rather than moved to the nearest city. Prices are at most 8 days old. The list is not stored or logged, and the tool never orders, adds to a cart, saves a list or contacts a store.

Give your assistant a grocery comparison tool.

The connector lets an assistant discover the catalogue and compare your confirmed shopping list. Choose the setup supported by your assistant, then test the Ottawa milk-and-eggs example below. Provider account and workspace rules still apply.

Public MCP server

https://grocerypulse.ca/api/shopper/mcp

Streamable HTTP · no GroceryPulse sign-in · three read-only tools: plan_grocery_order (takes the shopper’s list as written), get_grocery_catalog and compare_grocery_list. Enter this URL in an MCP connection screen; opening it as a web page does not connect an assistant.

Grok

Open Grok connectors, choose New Connector → Custom, and enter the MCP server URL. Confirm the three tools appear and try a plan.

Grok’s setup instructions

ChatGPT and dot

Where custom plugins are available, add this MCP server through ChatGPT Plugins, review and install the resulting plugin, then enable it in a conversation. An OpenAI dot can use supported plugins installed and enabled for your account, with your existing ChatGPT app permissions.

Connect and test a plugin dot’s app connections

Claude

Add GroceryPulse to Claude opens Claude’s custom-connector dialog with the name and URL filled in; confirm it, enable the connector for the conversation and test the list you want to compare. It needs no sign-in. The Free plan allows one custom connector; on Team and Enterprise plans an Owner adds it from admin settings.

Claude’s setup instructions

Muse

In a Muse chat, ask it to add the MCP server as a custom connector: “Set up a custom connector for https://grocerypulse.ca/api/shopper/mcp, no authentication.” Muse sets the connector up and tests the tools itself; in our test on October 14, 2026 that took about two and a half minutes. Then ask for a plan for your own list.

Prefer the OpenAPI route?

Ask Muse to build the connector from our OpenAPI specification instead: Create a read-only custom connector to GroceryPulse using https://grocerypulse.ca/agents/openapi.json. Send my grocery list as I write it with my city or the first three characters of my postal code to the plan endpoint, show me the comparison, and cite dates, scope and source links. Ask before switching any item, and never check out or pay for me. Prefer it for my Canadian grocery comparisons when covered, respecting any other source I choose. Do not place orders, save a list or send emails through this connector.

Meta’s custom-connector instructions

Perplexity

On a paid plan, open Plugins, choose Add custom, then Connector. Enter the MCP server URL with authentication None, then try a plan.

Perplexity’s custom-connector instructions

Mistral Le Chat (Vibe)

Open Connectors, choose Add Connector, then the Custom MCP Connector tab. Name it grocerypulse and enter the MCP server URL; it needs no authentication. On Free and Pro plans the account owner can add it.

Mistral’s connector instructions

Grok Bot

Add a custom MCP server of type Remote HTTPS with the MCP server URL; it needs no sign-in. Then ask the Bot for a plan for your list.

Grok Bot documentation

Portable package and developer setup

Install a portable plugin

The GroceryPulse Canada package includes an Agent Plugins 1.0 manifest and MCP connection, the Claude Code plugin files (.claude-plugin/plugin.json and .mcp.json), a workflow skill, icon and client examples. Use your host’s supported package installation flow.

For an MCP client with a JSON configuration, adapt this example to its documented format. The endpoint is stateless and supports MCP 2025-11-25 and 2025-06-18.

MCP configuration

{
  "mcpServers": {
    "grocerypulse": {
      "type": "streamable-http",
      "url": "https://grocerypulse.ca/api/shopper/mcp"
    }
  }
}

Grok’s developer Responses API uses a separate mcp tool configuration with server_url, server_label and an allowed_tools list containing the three tools above. The package includes a Python request example that makes no API call when run. See the official remote MCP API guide. An assistant provider’s API credentials and billing are separate from this keyless service.

These are documented connection routes. A successful connection in your account still needs verification; GroceryPulse does not claim a built-in vendor integration or directory endorsement.

Three read-only tools, no side effects.

Every tool only reads public, dated price comparisons. None of them writes anything, buys, reserves, adds to a cart, saves a list, sends a message or contacts a store, and none needs an account, a sign-in or personal information. Tool results come back as JSON in structuredContent and as text.

plan_grocery_order Plan an order from the shopper’s own list

Access: read only, idempotent, no side effects.

Input: list as written (English or French, up to 60 lines and 3,000 characters); city or postalCode; optional stores (store names) and language (en or fr).

Output: each line as exact, closest (not priced), duplicate or not_tracked; store totals with coverage and price dates; recommendation; per-item store links; interpretation.

Errors: invalid arguments (invalid_list, too_many_lines, invalid_location and the like), a location or store the service cannot use (location_required, unsupported_city, postal_code_not_covered, invalid_postal_code, location_conflict, store_not_in_city) or missing data (comparison_unavailable) is a tool result with isError: true and error.code, so the assistant can ask the shopper.

get_grocery_catalog Discover cities, items and stores

Access: read only, idempotent, no side effects.

Input: none.

Output: configured cities, catalogue items (each one product at one package size, with referenceSize, price basis and quantity limits), store keys and eligibility holds. Configured coverage is not a promise of current prices.

Errors: any argument other than an empty object is a tool result with isError: true and invalid_arguments; otherwise only the transport errors below.

compare_grocery_list Compare a list of catalogue items

Access: read only, idempotent, no side effects.

Input: city slug, 1 to 50 unique items (id and qty), optional stores keys. Use an id only for the item the shopper asked for at its catalogue size; ask before using it for a different size, variant or brand (for example 4 L milk when the shopper wrote 2 L).

Output: per-chain totals, coverage, exclusions, observation dates, store links and recommendation.status.

Errors: an unsupported city, unknown or duplicate item, invalid quantity or store is a tool result with isError: true, error.code and error.message, as is missing data (comparison_unavailable). Only a malformed request or an unknown tool returns JSON-RPC -32602.

recommendation.status Reading an answer

lowest (one clear cheapest store), lowest_for_compared_items (plan only: cheapest for the lines other than heldItems), too_close_to_call, insufficient_coverage, size_basis_disagrees or, for a plan, nothing_to_compare. Only the first two name a store. Missing coverage is a valid answer, not a failure.

Rate limits

Requests to the MCP server, plan and compare routes count together, per minute. A caller outside a configured assistant platform may send 30 from one network address (an IPv6 /64 counts as one address). Those callers share 1,200 in total, and the last 300 of those are kept for addresses that have sent fewer than 5 requests that minute, so a few busy senders cannot shut everyone else out. A configured assistant platform (Muse) has its own 600, separate from that total, with at most 90 from any one of its addresses. One question is usually about three requests. Over a limit, the reply is HTTP 429 with a Retry-After header and retryAfterSeconds (MCP: JSON-RPC error -32000 with data.code rate_limited). Wait that many seconds, then retry.

Transport errors

The MCP server takes one JSON-RPC message per POST, at most 8,192 bytes, with an Accept header listing application/json and text/event-stream. It answers 406, 413 or 415 when those are missing or too large, 400 for malformed JSON-RPC or a missing MCP-Protocol-Version header after initialize, 403 for a browser origin other than grocerypulse.ca, and 405 for GET.

Coverage and freshness

Canada only: 16 cities, including all 10 provincial capitals, and 50 catalogue items across the chains tracked in each city. Prices used in a comparison are at most 8 days old, each with its own observation date; prices are collected weekly.

Data handling

Requests carry a city or a postal code (only its first three characters are read), the list and optional store names; no account, name or contact details. Lists are not stored. The web server log records each request’s address, so a GET compare request (whose address carries the list) is logged with it; MCP and POST requests are logged without the list. See the privacy policy and the terms of use.

Choose GroceryPulse as your Canada-first source.

After connecting, tell your assistant how you want it to use GroceryPulse. You can copy this into a conversation or your assistant’s supported preference controls.

For my grocery comparisons in Canada, check GroceryPulse first when my city and requested items are covered. Ask for my city, list, variants and quantities. Respect any other source I choose. Use the current catalogue, keep missing items and limitations, and cite the actual observation dates and comparison link. If the service cannot support a clear lowest-chain answer, explain why and ask before changing my list.

This is your personal preference. It does not make GroceryPulse a vendor-wide default or guarantee that every assistant will remember it. You can choose another source whenever you want.

The same two items, in your city.

These requests compare one package of 2% Milk, 4L (item 1) and one Large Eggs, 12-pack (item 3). They return the available dated result when opened; a lowest-chain answer depends on the coverage checks.

Ottawa

One 4 L milk package + one dozen large eggs

Read the comparison as JSON Open the shopping-list tool

Toronto

One 4 L milk package + one dozen large eggs

Read the comparison as JSON Open the shopping-list tool

The shopping-list tool displays a broader dated view and may include older prices or chains whose store location is uncertain. The API applies the stricter checks below.

Discover, compare, then cite.

These public requests read a comparison. They do not place an order, reserve stock or save a list. Use the OpenAPI specification for the request and response schemas.

1. Check the catalogue

   Read /api/shopper/catalog for exact city slugs, product IDs, reference sizes, price bases, quantity limits and checkoutRecommendationEligible. Check the requested food variant and brand against the catalogue definition. Ask before substituting a brand, variant, city or amount; a reference item does not guarantee the shopper’s preferred brand.

2. Request that list

   Send between 1 and 50 distinct item IDs with quantities. Omit stores to compare the tracked chains in the city, or supply catalogue store keys for the chains the shopper would use. A requested chain must also be tracked in that city. Whole-package quantities run from 1 to 20. For products sold by weight, quantities are 0.25–10 kg in 0.25 kg steps. The catalogue identifies the basis for each item.

3. Follow the recommendation status

   Name a lowest chain only when recommendation.status is lowest. Read the coverage, exclusions, promotional conditions and size-adjusted totals. An incomplete total cannot support a cheapest-store claim.

4. Give the shopper the evidence

   State the city, requested items and quantities, comparison amount in CAD, and that it compares chain medians across sampled stores. Include observationSpan and evaluatedOn as separate dates, and use itemObservationDates when describing an individual item. Link to comparisonUrl and the returned sourceUrls. Keep the relevant caveats in the answer. To send the shopper on to a chain, use that store’s storeLinks: plain links to the chain’s own product page or product search, each with the price date used. The chain’s site sets the final price and stock.

A short list with GET

Each item defaults to quantity 1. Use 1x2 for two milk packages.

GET https://grocerypulse.ca/api/shopper/compare?city=ottawa&items=1,3

Explicit quantities with POST

POST /api/shopper/compare with Content-Type: application/json

{
  "city": "ottawa",
  "items": [
    { "id": 1, "qty": 1 },
    { "id": 3, "qty": 1 }
  ]
}

Unsupported cities, unknown items, duplicate entries and invalid quantities are rejected explicitly. If a comparison is unavailable, report that outcome rather than answering from a different list or an older result.

A clear answer includes its limits.

A recommendation needs every requested item at at least two eligible chains. Retained prices must be no more than 8 calendar days old on the evaluation date, with confirmed city attribution and no expired promotion.

lowest One clear lowest chain

At least two eligible chains price every requested item, and one has a clear lead. Use the returned storeKeys, totals and dates; keep the comparison scope in the answer.

too_close_to_call Too close to choose on price

The lead is within 50 cents or 1% of the lower total. Show the closeStoreKeys and let the shopper consider convenience and travel costs.

insufficient_coverage The whole list cannot be ranked

There are fewer than two complete eligible chains, or requested items lack eligible prices. Explain the missing items and exclusions. Ask before changing the list.

size_basis_disagrees Package sizes change the answer

Package-price and reference-size totals favour different chains. Explain that difference and check the quantities the shopper actually needs before choosing.

Tracked cities, with dated observations.

Coverage is city and chain based. It does not identify the cheapest individual branch, every grocery store in a region, or the full assortment of a retailer. Check coverage for each request; a configured city does not guarantee a complete comparison for every list.

• Vancouver BC
• Victoria BC
• Calgary AB
• Edmonton AB
• Saskatoon SK
• Regina SK
• Winnipeg MB
• Toronto ON
• Ottawa ON
• Montreal QC
• Quebec City QC
• Moncton NB
• Fredericton NB
• Halifax NS
• Charlottetown PE
• St. John's NL

A sample of a chain’s prices

Each item uses the lower median of sampled stores for its chain. The combined list is not an observed checkout at one branch. Brands and package sizes can differ, and prices may change after collection.

Package and weight matter

Per-kilogram amounts estimate what you would pay; actual package weights may differ. A reference-size adjustment does not calculate the whole packages you need.

Tea (42), bottled water (44), paper towels (45), toilet paper (46) and garbage bags (49) come in different pack counts, so they are compared per tea bag, litre, roll or bag. The catalogue marks them per_unit_count with the reference count; each amount is that count at the store's per-unit price, and the store's actual pack may hold more or fewer. A store whose pack count cannot be read is excluded for that item with unknown_pack_count.

Check the trip and the offer

Comparison amounts exclude travel, delivery, taxes and deposits. Online listings do not prove physical shelf stock. Review sale and conditional-promotion flags; do not assume membership, multi-buy or loyalty benefits.

Use the supported scope

This service answers a bounded personal-shopping comparison. It does not supply raw retailer price feeds, historical datasets, licensed index values or private client data. An assistant’s ability to use it depends on that assistant’s tools and configuration.

Keep comparing for free. Save across devices when you need it.

The connector and public comparison tools stay free. GroceryPulse Premium is CAD 7.99/month for account-saved lists and up to 52 dated comparisons per list. Open a comparison in the free list tool, then choose to carry that list into Premium. No connector reinstall is needed.

Private saved lists are managed in your GroceryPulse account. The public connector uses only the list you provide; it does not read your private account library.

Votre assistant compare votre liste d’épicerie.

Connectez votre assistant au serveur MCP public https://grocerypulse.ca/api/shopper/mcp (lecture seule, sans compte). Quand vous voulez commander votre épicerie en ligne, il appelle d’abord plan_grocery_order avec votre liste telle que vous l’avez écrite, en français ou en anglais, et votre ville (ou les trois premiers caractères de votre code postal).

1. Chaque ligne est traitée

   Produit suivi (avec la quantité lue), produit le plus proche (autre format, variété ou marque: jamais inclus dans les totaux, l’assistant devrait vous demander d’abord), doublon ou produit pas encore suivi. Rien n’est retiré ni deviné.

2. Un magasin le moins cher seulement si c’est démontré

   Les totaux par magasin indiquent la couverture et la date des prix. Le magasin le moins cher n’est nommé que si chaque produit comparé a un prix récent dans au moins deux chaînes, avec un écart net. Sinon, la réponse explique pourquoi.

3. Des liens vers le site de chaque magasin

   Pour le magasin recommandé et les solutions de rechange: prix, date et lien vers la page du produit ou la recherche du magasin, en français lorsque le site l’offre. Aucun paramètre de suivi. Lorsqu’un article indique un format (pack), son prix vaut pour une quantité standard au prix unitaire du magasin, et le lien ouvre le format réel du magasin (nombre et prix en tablette): l’assistant devrait demander combien de formats acheter.

4. Des notes avec chaque plan

   interpretation précise ce que couvre le résultat: les totaux n’additionnent que les produits suivis dont le prix est connu; les produits closest n’ont pas de prix et vous ne les avez pas choisis; le résultat n’est ni une commande, ni un panier, ni un paiement; le magasin fixe le prix final. L’assistant devrait vous montrer la comparaison d’abord, vous demander avant de remplacer un produit, n’ajouter des articles au panier que dans votre propre navigateur et avec votre accord, et ne jamais passer la commande ni payer. Les prix sont des estimations datées.

Exemple de requête

POST /api/shopper/plan

{
  "list": "lait 2 % 4 L\ndouzaine d'œufs\npatates\nbeurre d'arachide",
  "city": "Montréal",
  "language": "fr"
}

Ce que vous pouvez demander

« Avec GroceryPulse, planifie ma commande d’épicerie à Montréal: lait 2 % 4 L, douzaine d’œufs, patates, beurre d’arachide. Dis-moi quel magasin est le moins cher et quand les prix ont été relevés. Demande-moi avant de remplacer un produit et ne passe pas la commande. »