**Repository:** [gitlab.com/mayutic/ration/application](https://gitlab.com/mayutic/ration/application) — hosts **Ration**, an AI-powered kitchen management app, and its dedicated **MCP server** (`mcp.ration.mayutic.com`).

# Ration MCP Server

> **AI-powered kitchen management for your assistant** — live pantry inventory, cook-from-stock recipes, weekly meal plans, and shopping lists. **AI connectivity via MCP** (Model Context Protocol) lets Claude, Cursor, ChatGPT, and other agents read and update your kitchen with scoped OAuth consent — same data as the web app, no shadow copy.

**Homepage:** [ration.mayutic.com](https://ration.mayutic.com) · **Connect:** [ration.mayutic.com/connect](https://ration.mayutic.com/connect) · **Start free** — no credit card required.

---

## The complete kitchen loop for your AI

Most kitchen apps make *you* maintain the spreadsheet. Ration closes the loop:

**Cargo** (pantry) → **Galley** (recipes) → **Manifest** (meal plan) → **Supply** (shopping list) → dock back into Cargo.

Your MCP client operates the same data you see in the web app — not a shadow copy. Semantic matching links recipe ingredients to pantry items even when names differ (`"2% milk"` vs `"whole milk 2%"`). Expiry-aware tools help you cook what you have before it spoils.

**Free to start:** 35 pantry items, 15 recipes, 3 supply lists, full MCP access, and 12 welcome credits for new human accounts. Upgrade to **Crew Member** (€2/month or €12/year) for unlimited capacity, household sharing, and invite links.

---

## Same prompt, better answer

### Without Ration

> "What can I make tonight?"

Your assistant guesses. It does not know what is in your fridge, what expired yesterday, or what is on Thursday's plan.

### With Ration MCP

> "What can I cook tonight with what's in Cargo?"

`match_meals` returns recipes ranked by what you can actually cook — with gaps listed for anything missing. Ask follow-ups: add missing items to Supply, schedule a meal on Manifest, deduct ingredients after you cook.

---

## What you can say

| Prompt | What happens |
|--------|----------------|
| "How's my kitchen?" | `get_kitchen_summary` |
| "What did I cook last week?" | `get_kitchen_events` / `get_kitchen_stats` |
| "List my pantry and what's expiring this week." | `list_inventory` + `get_expiring_items` |
| "What already expired in my pantry?" | `get_expired_items` |
| "What meals can I make with what we have?" | `match_meals` (strict or partial matches) |
| "Plan dinners through Friday and add anything missing to the list." | `propose_manifest_plan` → `commit_manifest_plan` → `sync_supply_from_selected_meals` |
| "We cooked lentil soup for four — update inventory." | `consume_meal` deducts ingredients via semantic matching |
| "Add eggs and butter to the shopping list." | `add_supply_item` |
| "I bought everything on the list — mark it purchased." | `mark_supply_purchased_bulk` |
| "Parse this receipt and add new items to Cargo." | Agent parses text → `preview_inventory_import` → `apply_inventory_import` (no Ration AI credits) |
| "I ate two cans of tuna." | `adjust_cargo_item` with `delta: -2` (floors at 0; line stays for restock) |

MCP tool calls are **deterministic and do not consume Ration credits**. Receipt parsing runs in *your* LLM; Ration ingests structured items. Visual scan and AI meal generation in the web app use optional credit packs.

---

## Why Ration MCP is different

- **Closed-loop kitchen ops** — inventory, recipes, plan, and shop list in one system (not four apps).
- **35+ MCP tools** — granular OAuth scopes (`mcp:read`, `mcp:inventory:write`, `mcp:galley:write`, `mcp:manifest:write`, `mcp:supply:write`, `mcp:preferences:write`), including optional nutrition summary/goals when flags are on.
- **OAuth-first** — paste one URL; browser sign-in; revoke anytime in Hub → Settings → Connected Agents.
- **Agent self-registration** — autonomous agents can provision a kitchen via [`auth.md`](https://ration.mayutic.com/auth.md) before a human signs up.
- **Household-scoped** — one organization per grant; pick the correct household at consent.
- **Edge-hosted** — Cloudflare Workers, D1, Vectorize semantic search.

---

## Connect in about 2 minutes

### OAuth (recommended)

1. In your MCP client, add server URL:

   ```
   https://mcp.ration.mayutic.com/mcp
   ```

2. Complete browser sign-in, **select your household**, and approve scopes.
3. Ask: *"List my Ration pantry."*

**Works with:** Cursor · Claude Desktop · Claude Code · ChatGPT desktop · Zed · any MCP client with OAuth 2.1 discovery

**One-click setup:** [ration.mayutic.com/connect](https://ration.mayutic.com/connect)

### Advanced: API key

Create an organization API key with `mcp:*` scopes in Hub → Settings → API Keys. Use a Bearer header or `mcp-remote` bridge. See [API docs](https://ration.mayutic.com/docs/api#mcp).

### Autonomous agents (agent-first onboarding)

Your MCP client can provision a kitchen without human signup:

1. Read [auth.md](https://ration.mayutic.com/auth.md) for the registration and claim contract.
2. `POST /api/agent/auth` with `{ "type": "anonymous" }` — returns a **full-write** API key, claim URL, and MCP endpoint (once).
3. Configure MCP with the returned key as a Bearer header.
4. Human claims via OTP at [ration.mayutic.com/connect/claim](https://ration.mayutic.com/connect/claim) whenever ready.

Full walkthrough with client-specific setup (Claude, Cursor, ChatGPT, Goose): [Agent-First MCP Onboarding](https://ration.mayutic.com/blog/agent-first-mcp-onboarding).

---

## MCP tools reference

All tools are scoped to the authorized household. **MCP calls do not consume Ration credits.** Destructive tools require `confirm: true`.

### Read & account

| Tool | Scope | Description |
|------|-------|-------------|
| `get_context` | `mcp:read` | Return org id, scopes, kitchen tier/usage/credits/lastActivityAt, capabilities, suggested next actions, and `temporal` (todayUtc, server time, expiry semantics). Safe to call first. |
| `search_ingredients` | `mcp:read` | Semantic pantry search by meaning — find items without knowing the exact name. |
| `list_inventory` | `mcp:read` | Cursor-paginated pantry list (default 100, max 200). Optional domain filter, UTC `expiresBefore` / `expiresAfter`, and `sortBy: expiresAt`. Includes `nutrition` when present. |
| `get_cargo_item` | `mcp:read` | Fetch one pantry item by id (tags, expiry, custom fields, nutrition when present). |
| `get_kitchen_summary` | `mcp:read` | Single-call operational snapshot (cargo, manifest, supply, tier/credits). Optional `manifestDays` (1–7). |
| `get_kitchen_events` | `mcp:read` | Flight Recorder timeline of cooks, docks, expiries, and jettisons (filterable, paginated). |
| `get_kitchen_stats` | `mcp:read` | Flight Recorder aggregates for a window (7d/30d/90d/365d). |
| `get_expiring_items` | `mcp:read` | List items expiring within N UTC calendar days (defaults to user `expirationAlertDays`). |
| `get_expired_items` | `mcp:read` | List items whose expiry date is before today (UTC). Optional `daysBack` (default 30). |
| `list_meals` | `mcp:read` | Cursor-paginated recipe list. Set `includeIngredients: false` for a lightweight index. |
| `match_meals` | `mcp:read` | Find cookable recipes from current pantry — `strict` or `delta`. Adds `allergenFlags` when user allergens are configured. |
| `get_meal_plan` | `mcp:read` | Weekly meal plan entries by date and slot (`cookedAt`/`consumedAt`; `personalIntake` when nutrition flags allow). |
| `get_supply_list` | `mcp:read` | Active shopping list with item ids for updates and purchase toggles. |
| `get_user_preferences` | `mcp:read` | Allergens, expiration alert days, theme, manifest defaults, and other user settings. |
| `update_user_preferences` | `mcp:preferences:write` | Patch user settings (allergens, alerts, theme). Only provided fields change. |
| `get_nutrition_summary` | `mcp:nutrition:read` | Caller’s personal daily intake totals (energy/macros/optional fiber) for a UTC `from`/`to` range (requires `nutrition-goals` or `nutrition-manifest`). When `nutrition-cross-org-diary` is on, includes every kitchen the user logged—not household nutrition. Agent reads audited. |
| `list_nutrition_intakes` | `mcp:nutrition:read` | Caller’s personal intake rows for a UTC range (cursor-paginated; kitchen labels when present). Cross-org when `nutrition-cross-org-diary` is on. Agent reads audited. |
| `set_nutrition_goal` | `mcp:nutrition:write` | Idempotently upsert personal daily energy/macro/fiber goals using `operationKey`; consent must already be active in Ration. Not medical advice. |
| `clear_nutrition_goal` | `mcp:nutrition:write` | Idempotently close open-ended goals using `operationKey`. **Requires `confirm: true` + host approval.** |
| `log_manifest_intake` | `mcp:nutrition:write` | Atomic private Eat for 1–50 prepared entries (`operationKey` + per-item `idempotencyKey`). Multi-entry calls need host approval. Consent must already be active in Ration. |
| `clear_manifest_intake` | `mcp:nutrition:write` | Atomically soft-void personal intake using `operationKey`. **Requires `confirm: true` + host approval.** |
### Inventory (Cargo)

| Tool | Scope | Description |
|------|-------|-------------|
| `add_cargo_item` | `mcp:inventory:write` | Add a single pantry item (qty > 0). Optional `nutrition` override; when omitted and `nutrition-engine` is on, USDA auto-resolves. No credits; vectors backfilled async. Prefer import tools for bulk. |
| `update_cargo_item` | `mcp:inventory:write` | Set absolute fields (including optional `nutrition`). Quantity may be **0** (kept as a restock reminder). |
| `adjust_cargo_item` | `mcp:inventory:write` | Relative `delta` change (e.g. `-2` when the user ate 2). Floors at 0; keeps the row. |
| `remove_cargo_item` | `mcp:inventory:write` | Permanently delete a pantry line. **Requires `confirm: true`.** |
| `preview_inventory_import` | `mcp:inventory:write` | Dry-run receipt/bulk import — returns `previewToken` and sample rows. Prefer `ration://schemas/inventory-import` for shape. |
| `apply_inventory_import` | `mcp:inventory:write` | Commit a previewed import after chat confirmation. Idempotent via `idempotencyKey`. |
| `preview_inventory_remove` | `mcp:inventory:write` | Dry-run bulk Cargo deletes (prefer for 2+ items). |
| `apply_inventory_remove` | `mcp:inventory:write` | Commit a remove preview after chat confirmation. Idempotent. |
| `import_inventory_csv` | `mcp:inventory:write` | Parse and apply a CSV string in one call (convenience wrapper). |

### Galley (recipes)

| Tool | Scope | Description |
|------|-------|-------------|
| `create_meal` | `mcp:galley:write` | Create a recipe from structured data. |
| `update_meal` | `mcp:galley:write` | Update a recipe — round-trip via `list_meals` → edit → pass full object. |
| `delete_meal` | `mcp:galley:write` | Delete a recipe. **Requires `confirm: true`.** Cascades to ingredients, tags, and linked Manifest entries. |
| `set_active_meals` | `mcp:galley:write` | Set Galley active selection to exactly these mealIds. Optional `syncSupply`. |
| `clear_active_meals` | `mcp:galley:write` | Clear all active meal selections. **Requires `confirm: true`.** |
| `consume_meal` | `mcp:galley:write` + `mcp:inventory:write` | Cook and deduct ingredients from pantry. When cook-log-split is on, bridges to Manifest Prepared (no personal intake). Requires **both** scopes. |

### Manifest (meal plan)

| Tool | Scope | Description |
|------|-------|-------------|
| `add_meal_plan_entry` | `mcp:manifest:write` | Schedule a meal on a date and slot. |
| `commit_manifest_plan` | `mcp:manifest:write` | Commit a confirmed multi-entry schedule (optionally sync supply). |
| `update_meal_plan_entry` | `mcp:manifest:write` | Patch date, slot, servings, or notes. Cannot edit consumed entries. |
| `remove_meal_plan_entry` | `mcp:manifest:write` | Remove a scheduled plan entry. |
| `cook_manifest_entries` | `mcp:manifest:write` + `mcp:inventory:write` | Shared Cook (Cargo + Prepared). Requires `nutrition-cook-log-split`. Never logs intake. |
| `consume_manifest_entries` | `mcp:manifest:write` + `mcp:inventory:write` | Legacy combined consume. Refused when cook-log-split is on — use cook then `log_manifest_intake`. Requires **both** scopes. |

### Supply (shopping list)

| Tool | Scope | Description |
|------|-------|-------------|
| `add_supply_item` | `mcp:supply:write` | Add a line to the active shopping list. |
| `update_supply_item` | `mcp:supply:write` | Update name, quantity, or unit on a supply line. |
| `remove_supply_item` | `mcp:supply:write` | Remove a supply list line. |
| `mark_supply_purchased_bulk` | `mcp:supply:write` | Mark one or many supply lines purchased / unpurchased. |
| `sync_supply_from_selected_meals` | `mcp:supply:write` | Rebuild list from meal plan + Galley selections (buy only the delta). |
| `complete_supply_list` | `mcp:supply:write` + `mcp:inventory:write` | Dock purchased items into pantry and archive the list. Requires **both** scopes. **Requires `confirm: true`.** |

Server card: [`.well-known/mcp/server-card.json`](https://ration.mayutic.com/.well-known/mcp/server-card.json) · Full API reference: [docs/api](https://ration.mayutic.com/docs/api#mcp-tools)

---

## Pricing

| Tier | Includes |
|------|----------|
| **Free** | 35 pantry items · 15 recipes · 3 supply lists · MCP + OAuth · agent self-registration |
| **Crew Member** | Unlimited capacity · household invites · shared Manifest/Supply links · $2/mo or $12/yr |
| **Credit packs** (optional) | AI receipt scan, recipe import, meal generation, weekly AI plan in the **web app** — from €1 |

[MCP does not meter credits](https://ration.mayutic.com/blog/mcp-kitchen-assistant). Use the web app when you want hosted vision/AI features.

---

## MCP server details

| Field | Value |
|-------|-------|
| **Name** | Ration |
| **Endpoint** | `https://mcp.ration.mayutic.com/mcp` |
| **Transport** | Streamable HTTP (OAuth 2.1) |
| **Category** | Productivity |
| **Source** | [gitlab.com/mayutic/ration/application](https://gitlab.com/mayutic/ration/application) |
| **Homepage** | [ration.mayutic.com](https://ration.mayutic.com) |
| **Listing doc** | [ration.mayutic.com/mcp.md](https://ration.mayutic.com/mcp.md) |
| **Built by** | [Mayutic](https://www.mayutic.com) |

### mcpservers.org submission (copy-paste)

- **Server name:** Ration
- **Short description:** AI-native kitchen MCP — pantry inventory, cook-from-stock recipes, meal plans, and shopping lists with OAuth and 35+ tools. Free to start.
- **Link:** https://ration.mayutic.com/mcp.md
- **Category:** Productivity

---

## Learn more

- [Homepage & signup](https://ration.mayutic.com)
- [Connect your agent](https://ration.mayutic.com/connect)
- [Your Kitchen Has an API (blog)](https://ration.mayutic.com/blog/mcp-kitchen-assistant)
- [The Pantry Data Problem (blog)](https://ration.mayutic.com/blog/pantry-data-problem)
- [REST API v1](https://ration.mayutic.com/docs/api)

---

*Ration — manage your kitchen through your AI agent.*