To start developing with Recall Kitchen, you'll need:
- An API key from the MCP
signup tool, or the app's Integrations page
- Or try a few anonymous MCP searches (no key) from an explorer or demo, then sign up or pay with x402
- Or an x402-capable client for pay-per-request calls after the free IP quota
- Familiarity with HTTP APIs or MCP
Authentication
Create a key with the MCP signup tool (email, no existing key) or in the app under Integrations. Send it on every request as Authorization: Bearer rk_... or X-API-Key: rk_.... MCP and HTTP search use the same keys.
What is free, paid, or requires an account
- Free (no key):
initialize, tools/list, resources, prompts, and signup. A few search calls per IP (5/hour, 15/day): search_product_recalls, search_recalls_by_identifier, search_product_recalls_by_upc, lookup_product, get_product_recall. Image search is not free.
- Paid (x402, USDC on Base): anonymous search after the IP quota, and
search_product_recalls_from_image without a key. Account tools do not work with x402.
- Signup (email, no key): mints one API key, shown once. That unverified key is enough for all search (including image), up to 3 watch patterns, notifications, and
check_tracked_products. Limits: 60 tool calls/hour, 400/day, one key. No inventory.
- Verification: sign in at app.recallkitchen.com with the same email. Unlocks inventory and raises limits to 600/hour, 3,000/day, three keys, 20 watch patterns, and 50 inventory products.
Usage is counted per account, not per key. Protocol methods such as initialize and tools/list do not count. Rate-limited responses return HTTP 429 with a Retry-After header and a JSON hint to verify or pay with x402.
curl
Search recalls:
curl -sS -H "Authorization: Bearer rk_..." \
"https://app.recallkitchen.com/api/sources?q=spinach&limit=10"
Call an MCP tool:
curl -sS -H "Authorization: Bearer rk_..." \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_product_recalls","arguments":{"query":"spinach","limit":3}}}' \
https://app.recallkitchen.com/mcp
Fetch one recall (lots, UPCs, locations):
curl -sS -H "Authorization: Bearer rk_..." \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_product_recall","arguments":{"recall_id":"RECALL_ID"}}}' \
https://app.recallkitchen.com/mcp
Against a local server, swap the host for http://localhost:8080.
If a request fails or a client will not connect, email support@recallkitchen.com.
Agent Integrations (MCP, MPP, x402)
Recall Kitchen integrates with the Model Context Protocol (MCP) and
Machine Payment Protocol (MPP) standards for tool use by AI models.
Our MCP implementation leverages x402 (USDC on Base) for micropayments, enabling paid access to tools.
MCP
See what is free, paid, or requires an account. A few anonymous search calls per IP are free for explorers and demos; after that, anonymous calls are paid (USDC on Base, $0.025 per call) via x402. Tools are free with an API key. Inventory requires verification.
Search tools return compact recall objects with
id, source, title, a truncated description,
url, publishedOn, and up to five extracted products (lots/UPCs/locations).
Use get_product_recall for the full description and full extracted lists.
Prompts (check_product, check_upc, scan_image, check_vin) and resources
(recall://docs/tools, recall://docs/sources) are available.
Keyword, identifier, UPC, lookup, and get-by-id search: a few anonymous calls per IP are free, then an API key or x402. search_product_recalls_from_image (photo URL, data URI, or MCP image content) needs a key or x402; it is not in the free quota. Local file paths are not accepted. List tools support offset and return nextOffset when more results exist.
search_product_recalls
Search by query string. Query uses websearch syntax: unquoted words are AND, OR is or, -term excludes, quoted phrases match as a unit (example: Generac Generator -Portable). Optional filters: source (cpsc, fdafoodsafety, FDAMedWatch, usda, nhtsa, canada, costco, target, walmart, openfda), sources (OR list of those values), since/until, years (1–50, rolling published window; ignored if since is set), location (country, region, or place, ANDed with the query; CA matches California and "northern california"; United States does not match Canada/Ontario; Canada matches provinces; Mexico matches Mexican states, not New Mexico; EU / Europe match European countries), offset, and limit (1–100, default 3). Descriptions are truncated; call get_product_recall for the full text.
{
"query": "string",
"source": "string",
"sources": ["costco", "target"],
"since": "YYYY-MM-DD",
"until": "YYYY-MM-DD",
"years": 1,
"location": "string",
"offset": 0,
"limit": 3
}
search_product_recalls_by_upc
Search extracted recall UPCs by UPC/EAN, or pass a barcode image as an HTTPS URL or data:image/...;base64 URI. barcode is an alias for upc; url is an alias for image_url. Returns found=false with a hint when the UPC is unknown. Does not attach unrelated keyword hits.
{
"upc": "string",
"barcode": "string",
"image_url": "string",
"url": "string",
"limit": 3
}
search_product_recalls_from_image
Identify products in a public HTTPS image URL, a data:image/...;base64 URI (JPEG, PNG, GIF, WebP, BMP; max 8 MiB), or MCP image content (type: image with mimeType and base64 data). Local file paths are not supported. url is an alias for image_url. Each product includes match (upc, model, text, or category) and confidence. Category matches (generic cups, coolers, bowls) omit recalls unless include_category_matches is true. Requires an API key or x402; not included in the free anonymous per-IP quota. The signed-in app streams the same pipeline at POST /api/scan/stream (NDJSON events); this tool returns the final fused JSON so agents do not have to read the stream.
{
"image_url": "string",
"url": "string",
"limit": 3,
"include_category_matches": false
}
get_product_recall
Fetch one recall by id, including extracted lots, UPCs, model numbers, locations, stores, contact info, and product photo URLs hosted by Recall Kitchen.
{
"recall_id": "string"
}
search_recalls_by_identifier
Search extracted recall data by UPC, lot code, model number, product name, or VIN. Multiple fields are AND-matched on the same product. vin is decoded locally to year and make and matched against NHTSA campaigns (not a live unrepaired-VIN API).
{
"upc": "string",
"lot_code": "string",
"model_number": "string",
"product_name": "string",
"vin": "string",
"limit": 3
}
lookup_product
Look up a product by UPC. Returns name and USDA branded-food details when available. Returns found=false when unknown. Does not search recalls.
{
"upc": "string"
}
signup is free (no API key, no x402). The other account tools require an API key; x402 callers get an error. Unverified signup keys can add a few watch patterns. Inventory requires verification (sign in on the site with the same email).
signup
Create an account from an email and receive an API key once. No existing key or x402 payment. name is optional. Does not re-issue a key if the email already has an account. Unverified accounts have lower rate limits until you sign in at app.recallkitchen.com with the same email.
{
"email": "string",
"name": "string"
}
create_api_key
Create an additional API key for this account. Requires an existing API key. Unverified accounts may have only one key; verified accounts may have three. Usage is shared across keys. kind is user or agent (default agent).
{
"name": "string",
"kind": "agent"
}
list_api_keys
List this account's API keys (id, name, prefix, created). Secrets are not shown. Also returns the account's current limits. Requires an API key.
{}
revoke_api_key
Revoke an API key by key_id from list_api_keys. Requires an API key. Revoking the current key will fail subsequent calls.
{
"key_id": "string"
}
check_tracked_products
Check this API key's watch patterns and inventory against current indexed recalls (including historical notices). Does not create notifications. Generic patterns such as food or hazard only match whole words in titles, and are not used as search queries unless weight is 7+.
{
"limit": 3,
"offset": 0
}
list_watch_patterns
List this API key's recall watch patterns.
{}
add_watch_pattern
Add a recall watch pattern. Same websearch syntax as search_product_recalls (AND, OR, -exclude, quoted phrases). Weight is 0–8 and defaults to 4.
{
"pattern": "string",
"weight": 4
}
remove_watch_pattern
Remove a watch pattern.
{
"pattern": "string"
}
list_inventory
List this API key's tracked inventory products.
{
"query": "string",
"limit": 3
}
add_inventory_product
Add a product to this API key's inventory. Requires a verified account (sign in at app.recallkitchen.com with the signup email). Unverified keys cannot add inventory.
{
"name": "string",
"brand": "string",
"category": "string",
"sku": "string"
}
remove_inventory_product
Remove an inventory product by id from list_inventory.
{
"id": 1
}
list_recall_notifications
List recall notifications for this API key. unread defaults to true. Empty for new accounts until a new matching recall is published; this is not a backfill of check_tracked_products. Each item includes a short plain-text message. Open a notice in a browser at https://app.recallkitchen.com/r/{recall_id}.
{
"unread": true,
"limit": 3
}
mark_notification_read
Mark a recall notification as read (default) or unread. recall_id comes from list_recall_notifications. Requires an API key.
{
"recall_id": "string",
"read": true
}
x402 Payments
After the free per-IP search quota, anonymous MCP search calls require x402 payments (USDC on Base). Image search is never part of the free anonymous quota. Send an API key to skip payment. Account tools are not available over x402; call signup for a key.
MCP Endpoints
Recall Kitchen's MCP endpoint is https://app.recallkitchen.com/mcp
(or http://localhost:8080/mcp when running locally).
Authorization: Bearer rk_...
Grok, Claude Code, and Cursor
Most MCP clients have no API-key prompt in the add UI. Pass the key as an HTTP header. If a client still will not connect, email support@recallkitchen.com.
Grok
Use X-API-Key, not Authorization: Bearer.
Grok's HTTP MCP client treats a Bearer header as OAuth and fails initialize because Recall Kitchen does not implement MCP OAuth:
Auth required, when send initialize request
The --header flag is Name: value.
grok mcp add --transport http recall-kitchen https://app.recallkitchen.com/mcp \
--header "X-API-Key: ${RECALL_KITCHEN_API_KEY}"
Local:
grok mcp add --transport http recall-kitchen http://localhost:8080/mcp \
--header "X-API-Key: ${RECALL_KITCHEN_API_KEY}"
Or in ~/.grok/config.toml:
[mcp_servers.recall-kitchen]
url = "http://localhost:8080/mcp"
enabled = true
[mcp_servers.recall-kitchen.headers]
X-API-Key = "rk_..."
If you already added the server with Authorization: Bearer, change that header to X-API-Key and refresh with r in /mcps.
Claude Code
Claude Code sends Authorization as a static header (it does not start OAuth when you pass --header). Official form:
claude mcp add --transport http recall-kitchen https://app.recallkitchen.com/mcp \
--header "Authorization: Bearer ${RECALL_KITCHEN_API_KEY}"
Local:
claude mcp add --transport http recall-kitchen http://localhost:8080/mcp \
--header "Authorization: Bearer ${RECALL_KITCHEN_API_KEY}"
Cursor
Add to project .cursor/mcp.json or global ~/.cursor/mcp.json. Cursor interpolates ${env:VAR} in url and headers:
{
"mcpServers": {
"recall-kitchen": {
"url": "https://app.recallkitchen.com/mcp",
"headers": {
"Authorization": "Bearer ${env:RECALL_KITCHEN_API_KEY}"
}
}
}
}
Claude Code and Cursor send Authorization as a static header. Grok does not — it starts an OAuth handshake — so Grok must use X-API-Key.
Examples
Go client and examples (API key or x402) are in Recall-Kitchen/rk-mcp. Implementation notes: docs/mcp.md. Agent skill (which tool to call, query syntax, location traps): docs/skills/search-product-recalls/SKILL.md.
MPP
Coming Soon -
API Reference
Search recalls from software with an API key. Create keys in the app under Integrations, or with the MCP signup / create_api_key tools. Machine-readable OpenAPI 3.1 is at https://app.recallkitchen.com/openapi.json (x402scan / AgentCash discovery). x402 payment metadata is also at /.well-known/x402.
Search recalls
GET /api/sources?q=spinach&source=costco&source=target&since=2025-09-09&limit=10
The q parameter uses the same websearch syntax as search_product_recalls: unquoted words are AND, OR is or, -term excludes, quoted phrases match as a unit. Repeat or comma-separate source to include multiple. since and until are YYYY-MM-DD published bounds. The app computes since from the Last year / 3 years / 5 years control. Optional years=1 (up to 50) is a rolling shortcut if since is omitted.
curl -sS -H "Authorization: Bearer rk_..." \
"https://app.recallkitchen.com/api/sources?q=spinach&source=costco&source=target&since=2025-09-09&limit=10"
curl -sS -H "X-API-Key: rk_..." \
"http://localhost:8080/api/sources?q=spinach&limit=10"
Logged-in browser sessions continue to work without a key. Anonymous HTTP clients can pay with x402 instead.
Public recall pages
Each notice has a public permalink that does not require login: https://app.recallkitchen.com/r/{recall_id}. Share from the app uses this URL. The HTML includes Open Graph tags (title, description, and a public HTTPS image) so pasted links preview in iMessage, Slack, and similar. The same id is the JSON endpoint:
GET /api/recalls/{recall_id} (no auth)
curl -sS "https://app.recallkitchen.com/api/recalls/RECALL_ID"
The JSON includes the recall and extracted lots, UPCs, models, locations, and images. A missing id returns HTTP 404.
Session-authenticated app endpoints include image scan (POST /api/scan/stream NDJSON; event catalog in the OpenAPI document), inventory, watch patterns, notifications, GET /api/tracked (live watch/inventory check, same as check_tracked_products), and /api/keys. MCP tools cover UPC and image search for agents.
Questions about these endpoints: support@recallkitchen.com.
What recalls do you support?
We currently ingest United States CPSC, FDA (including openFDA enforcement), USDA, NHTSA vehicle recalls, Health Canada / CFIA recalls and safety alerts, plus retailer listings from Costco, Target, and Walmart. VIN search matches NHTSA campaigns for the decoded year and make; it does not call NHTSA's live unrepaired-VIN API.
How do I get an API key?
Call the MCP signup tool with an email, or sign in at app.recallkitchen.com, open Integrations, and create a key.
Send it as Authorization: Bearer rk_... on /mcp or /api/sources (Grok must use X-API-Key).
See curl and Grok / Claude Code / Cursor for copy-paste examples.
Free with no key: a few MCP searches per IP. Signup keys (unverified): 60 tool calls per hour and 400 per day, one key, and up to 3 watch patterns (no inventory). After you sign in with that email (verification): 600/hour and 3,000/day, three keys, 20 patterns, and 50 inventory products. Paid/admin: 1,200/hour and 10,000/day. After the free IP quota, anonymous clients can pay per request with x402. See access.
Can I share a recall?
Yes. Every notice has a public page at https://app.recallkitchen.com/r/{recall_id} (no login).
In the app, Share opens that URL. Pasted links preview the recall title and image. Agents can use the same id with get_product_recall or GET /api/recalls/{recall_id}.
How are Scan photos and barcode camera frames handled?
Photo uploads and MCP image tools send the image to our servers. Stored copies are used to match recalls and, by default, to improve detection.
The in-app barcode camera reads UPC and EAN codes in the browser; those frames are not uploaded.
See the Privacy Policy.
Who do I contact with questions?
Email support@recallkitchen.com for API keys, rate limits, MCP client setup (Grok, Claude Code, Cursor), or anything else in these docs.