API DOCUMENTATION / PRODUCTS CONNECTOR
Products connector
Find grocery and household products and dated prices at nearby stores.
What it is
Identify grocery and household products by name or barcode and see dated price observations at nearby stores, the cheapest first, plus a price summary (lowest, median, highest) for a product. About 28,000 products and 45,000 price observations, densest around Mountain View and the South Bay, California and New York City. Product data © Open Food Facts contributors (ODbL); prices © Open Prices contributors (ODbL); store locations © OpenStreetMap contributors (ODbL). Prices are observations with a date, not live shelf prices. Preview data: coverage is partial and fields may change. Every record links to its sources; check anything important at the source.
Connect
Endpoint: https://products-mcp.headcountlabs.com/mcp/public/products. It uses Streamable HTTP, is stateless and takes POST requests only. No account or key is needed. The data is read-only and U.S. only.
Example prompts
- What is barcode 00016000275263?
- Cheapest recent price for eggs near Mountain View, CA.
- Which stores near downtown Mountain View have recorded prices, and when were they last observed?
- Compare $11 with recorded prices for barcode 00861745000027 (Vital Farms organic large eggs, 12 count).
- Find Cheerios products.
Tools
These are the tools the endpoint returns from tools/list. A * marks a required input.
| Tool | What it does | Inputs |
|---|---|---|
find_prices | Find the cheapest recently observed shelf prices for a product, cheapest first, with the store and the date seen. | q, gtin, lat, lon, radius_m, since_days, limit, cursor, fields |
get_product | One grocery or household product by UUID or barcode (gtin: UPC-A, EAN-13, EAN-8 or GTIN-14): name, brand, size, and prices in the last 180 days. | id, gtin, fields |
find_products | Find products by words in the name (fuzzy, best match first) and/or exact brand, with barcode and size. | q, brand, limit, cursor, fields |
find_stores | Grocery and other stores near a point that have prices in the index (Open Prices), nearest first, with how many prices were seen there and the latest date. | lat*, lon*, radius_m, walk_minutes, q, limit, fields |
price_stats | Price statistics for one product (gtin) or the products matching q (top 10 by number of prices), optionally only stores near a point. | gtin, q, lat, lon, radius_m, since_days |
get_product_record | The full stored record of one product by its UUID (the id returned by find_products, find_prices or get_product): every field with the source it came from. | id* |
Every tool only reads public records and changes nothing. Pages hold at most 100 items, 20 by default. fields trims each item. Record IDs are for follow-up calls only.
Limits
Rate limits: 20 tool calls per minute per conversation (ChatGPT openai/session or the Mcp-Session-Id issued at initialize) and 600 requests per minute per network; over the limit, a tool call returns isError with the wait time and HTTP requests get 429 with Retry-After.
Responses are capped at 60,000 characters (items trimmed from the end, meta.truncated set).
Errors
A failed call returns an MCP tool result with isError: true and the API error JSON (invalid_parameter 400 naming the parameter, not_found 404, invalid_cursor 400, query_timeout 503 asking for a narrower search, read_only 503). Unknown tools and record paths outside this index are refused with a message. JSON-RPC errors: -32700 parse error, -32601 unknown method. HTTP 405 for GET/DELETE, 413 over 256 KB.