MCP tools reference
All tools are scoped to the authorized household (OAuth grant or API key organization). Nutrition read tools (get_nutrition_summary, list_nutrition_intakes) return the caller’s personal diary; when nutrition-cross-org-diary is on, totals/history include intakes from every kitchen that user logged—not “household nutrition.” Writes still authorize against the grant kitchen for that entry. MCP and Copilot kitchen tools do not consume AI credits; they use rate limits instead. Billed Gemini jobs (scan, URL import, Galley Generate, Plan Week) stay on native web/iOS only. Copilot invents meals with create_meal and fills a week with propose_manifest_plan → commit_manifest_plan. Every tool returns a uniform JSON envelope ({ ok: true, tool, data, warnings?, meta? } or { ok: false, tool, error }). Failures include error.code (including timeout), error.message, optional error.details, and often error.recoveryHint. Copilot returns the same envelope shape to the model. Tool handlers are capped (~20s) so hung Workers AI/D1 calls cannot stall the agent forever.
Rate limit categories
| Category | Typical limit | Applies to |
|---|
mcp_list | 30 per 60s per org | Most read tools |
mcp_search | 20 per 60s per org | Semantic search + meal match |
mcp_write | 15 per 60s per org | Most writes |
mcp_supply_sync | 8 per 60s per org | Heavy supply rebuild |
mcp_write_per_key | 15 per 60s per key | Defends against compromised keys |
Exact windows may be tuned; if you hit limits, wait for the window to reset. Rate-limit details are also returned in the envelope's error.retryAfter and structured meta.rateLimit fields.
Inventory (Cargo)
| Tool | Scope | Purpose |
|---|
list_inventory | mcp:read | Cursor-paginated cargo list (default 100, max 200). Optional domain, expiresBefore / expiresAfter (UTC YYYY-MM-DD), and sortBy: expiresAt. |
get_cargo_item | mcp:read | Fetch one item by id with all fields (tags, expiresAt, customFields). |
search_ingredients | mcp:read | Semantic search in pantry by meaning. |
get_expiring_items | mcp:read | Pantry lines expiring within N UTC calendar days. Defaults to the user's expirationAlertDays when days is omitted. |
get_expired_items | mcp:read | Pantry lines whose expiry date is before today (UTC). |
get_kitchen_summary | mcp:read | Single-call kitchen snapshot. Prefer this over get_context for status. When mcp:nutrition:read is granted, may include caller-only personalNutritionToday. |
get_kitchen_events | mcp:read | Flight Recorder timeline (filter by event type / date range; paginated). |
get_kitchen_stats | mcp:read | Flight Recorder aggregates (7d/30d/90d/365d counts + top cooked meals). |
add_cargo_item | mcp:inventory:write | Add a single pantry item. Fuzzy Vectorize merge skipped; embeddings backfill async. |
update_cargo_item | mcp:inventory:write | Set absolute pantry fields. Quantity may be 0. |
adjust_cargo_item | mcp:inventory:write | Relative quantity change (delta). Prefer for “used/ate N”. |
remove_cargo_item | mcp:inventory:write | Permanently delete a pantry line. Requires confirm: true (Copilot host Approve binds confirm). |
Receipt → pantry workflow (no credits)
Prefer resource ration://schemas/inventory-import for the item shape.
| Tool | Scope | Purpose |
|---|
preview_inventory_import | mcp:inventory:write | Dry-run import. Returns previewToken, totals, sample rows + rowsOmitted, warnings. |
apply_inventory_import | mcp:inventory:write | Commits a preview after chat confirmation (no second host approval card). Idempotent. Embeddings do not block return. |
import_inventory_csv | mcp:inventory:write | Parse a CSV string and apply directly. |
Bulk Cargo remove (no credits)
| Tool | Scope | Purpose |
|---|
preview_inventory_remove | mcp:inventory:write | Dry-run bulk deletes (prefer for 2+ items). |
apply_inventory_remove | mcp:inventory:write | Commits a remove preview after chat confirmation (no second host card). Idempotent. |
Galley (Meals)
| Tool | Scope | Purpose |
|---|
list_meals | mcp:read | Cursor-paginated recipe list. |
match_meals | mcp:read | Cookability match (strict / delta). Includes compact nutrition.perServing and optional maxEnergyKcal (unknown kcal stays listed). |
create_meal | mcp:galley:write | Create structured recipe (credit-free). |
update_meal | mcp:galley:write | Update a recipe. |
delete_meal | mcp:galley:write | Delete a recipe. Requires confirm: true. Cascades to ingredients, tags, and linked meal plan entries. Returns deletedPlanEntryCount. |
set_active_meals | mcp:galley:write | Set active selection to exactly mealIds. Optional syncSupply (host approval only when syncing). |
clear_active_meals | mcp:galley:write | Clear all active selections. Requires confirm: true. |
consume_meal | mcp:galley:write + mcp:inventory:write | Cook by mealId and deduct cargo. When nutrition-cook-log-split is on, bridges to today’s Manifest (Prepared); never logs personal intake (offerPersonalLog hint only). |
Manifest (Meal plan)
| Tool | Scope | Purpose |
|---|
get_meal_plan | mcp:read | Meal plan entries for a date range (cookedAt/consumedAt; personalIntake when nutrition flags allow; gramsPerServing when recipe mass is known). |
propose_manifest_plan | mcp:read | Compact week proposal from expiring + match_meals. No writes. |
commit_manifest_plan | mcp:manifest:write | Commit confirmed entries; optional supply sync. Approval required. |
add_meal_plan_entry | mcp:manifest:write | Schedule one meal. |
update_meal_plan_entry | mcp:manifest:write | Patch an unconsumed entry. |
cook_manifest_entries | mcp:manifest:write + mcp:inventory:write | Shared Cook: deduct Cargo once and mark Prepared. Requires nutrition-cook-log-split. Never logs intake. |
consume_manifest_entries | mcp:manifest:write + mcp:inventory:write | Legacy combined consume. Refused when nutrition-cook-log-split is on (cook_eat_split_required). When split is off, optional logNutrition (default false for agents). |
remove_meal_plan_entry | mcp:manifest:write | Remove a scheduled entry. |
Nutrition
Gated by nutrition feature flags. Not medical advice. Cargo/meal read and write tools may include a nutrition snapshot when present. Require mcp:nutrition:read / mcp:nutrition:write. Legacy broad mcp never grants nutrition; migrate keys to explicit kitchen scopes and re-issue or re-consent for nutrition. Agent personal nutrition reads are value-free audited (fail closed). Tools return schema-valid structuredContent plus text; clears and multi-entry intake writes need host approval. Mutation timeouts return timeout_ambiguous — retry with the same operationKey.
| Tool | Scope | Purpose |
|---|
get_nutrition_summary | mcp:nutrition:read | Daily intake totals (energy + macros + optional fiber) for a UTC date range, plus active goal and additive vsGoal remaining/overage for the last day. from/to default to today UTC. Requires nutrition-goals or nutrition-manifest. |
list_nutrition_intakes | mcp:nutrition:read | Row-level personal intake history for a UTC range (cursor-paginated). |
set_nutrition_goal | mcp:nutrition:write | Idempotently upsert a personal daily goal using operationKey (active consent required). Requires nutrition-goals. |
clear_nutrition_goal | mcp:nutrition:write | Idempotently clear the active goal as of a date using operationKey. Requires nutrition-goals. confirm: true. |
log_manifest_intake | mcp:nutrition:write | Atomic private Eat / plate-up for prepared entries (operationKey + portions[] with per-item keys). servings is 0.01–100, or amount+unit (serving | g | oz) when get_meal_plan gramsPerServing is present. Consent must already be active in Ration. Never deducts Cargo. |
clear_manifest_intake | mcp:nutrition:write | Atomically soft-void personal intake using operationKey. confirm: true. Does not uncook. |
quick_eat_cargo | mcp:inventory:write + mcp:manifest:write + mcp:nutrition:write | Personal Quick Eat: resolve by cargoId or name; create a missing line then eat (net 0 restock reminder). Manifest snack + optional private intake. Requires cargo-quick-eat + nutrition-cook-log-split. |
Supply (Shopping)
| Tool | Scope | Purpose |
|---|
get_supply_list | mcp:read | Active shopping list. |
add_supply_item | mcp:supply:write | Add a line. |
update_supply_item | mcp:supply:write | Patch a line. |
remove_supply_item | mcp:supply:write | Remove a line. |
mark_supply_purchased_bulk | mcp:supply:write | Mark one or many lines purchased (max 50). |
sync_supply_from_selected_meals | mcp:supply:write | Rebuild supply from plan + selections. |
complete_supply_list | mcp:supply:write | Dock purchased → cargo. |
Account & preferences
| Tool | Scope | Purpose |
|---|
get_context | mcp:read | Org/key context, slim kitchen tier/credits, capabilities. Prefer get_kitchen_summary for full status. |
get_billing_summary | mcp:read | Tier, credits, renewal, billing links. |
get_user_preferences | mcp:read | Allergens, alert days, theme, units. |
update_user_preferences | mcp:preferences:write | Patch preferences. |
Not exposed
- Camera/OCR receipt scan as a tool (text → preview/apply, or native Scan)
- Recipe URL scraping (
start_import_url does not exist). Copilot hard-blocks URL paste → Galley Import. MCP clients extract caption/page text with the client LLM, then create_meal.
- Billed Galley Generate / Manifest Plan Week as tools. Use
create_meal and propose_manifest_plan → commit_manifest_plan. Native buttons remain on web/iOS.
Large Galley JSON imports use the REST API with galley scope—not MCP.
Ration