Agent Documentation
Ration API and MCP Discovery
Ration exposes kitchen data to agents through a scoped REST API and a dedicated MCP server for conversational kitchen operations.
REST API
Send an organization-scoped API key with X-Api-Key or Authorization: Bearer <key>. Create keys in Hub → Settings → Developer → API Keys.
Base URL
/api/v1 on your Ration app origin (e.g. https://ration.mayutic.com/api/v1).
Rate limits
Exports: 30 requests/minute. Imports: 20 requests/minute.
Endpoints
| Endpoint | Method | Scope | Format |
|---|---|---|---|
| /api/v1/inventory/export | GET | inventory | CSV |
| /api/v1/inventory/import | POST | inventory | CSV |
| /api/v1/galley/export | GET | galley | JSON |
| /api/v1/galley/import | POST | galley | JSON |
| /api/v1/supply/export | GET | supply | CSV |
Example: Export inventory
curl -H "X-Api-Key: YOUR_KEY" https://ration.mayutic.com/api/v1/inventory/export
MCP Server
Connect an MCP-compatible AI client to https://mcp.ration.mayutic.com/mcp. Ration is AI-agent-ready: paste the URL, complete browser sign-in, select your household, and approve granular permissions — no manual API key for standard clients.
Recommended: OAuth 2.1
- In your MCP client, add server URL `https://mcp.ration.mayutic.com/mcp`
- Complete browser sign-in, select your household, and approve permissions (in that order)
- Manage or revoke access anytime in Hub → Settings → Developer → MCP
Supported clients
Cursor, Claude Desktop, ChatGPT desktop, Goose, Zed, Any MCP client with OAuth 2.1 discovery.
Manage grants in Hub → Settings → Developer → MCP. Discovery: MCP protected resource metadata, OAuth authorization server, MCP server card.
MCP OAuth troubleshooting
Browser shows "No authorization code received"
Your MCP client reached its OAuth callback without a code — usually Deny was clicked, the flow expired (~10 minutes), or an old browser tab was reused. Remove the MCP server in Cursor, re-add the URL, and complete sign-in → household → Authorize in one fresh tab. Prefer native URL config over mcp-remote when Cursor supports it.
Browser opens repeatedly or authorization fails
Revoke the grant below, remove the MCP server in your client, re-add the URL, and finish sign-in → household → authorize in one tab within a few minutes.
Agent listed here but tools fail
Revoke and reconnect — the grant may be incomplete (shows "Not linked"). Household selection is required for every new connection.
Wrong pantry data
Revoke and reconnect, choosing the correct household at the selection step.
Flows are short-lived (~10 minutes). Restart from your AI client if authorization expired — do not reuse an old browser tab.
Advanced: manual MCP auth
Organization API keys with mcp:* scopes remain supported for CI, custom headers, and legacy clients. Create keys in Hub → Settings → Developer → API Keys, then pass the key as a Bearer token via mcp-remote.
{
"mcpServers": {
"ration": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.ration.mayutic.com/mcp",
"--header",
"Authorization:${RATION_AUTH_HEADER}"
],
"env": {
"RATION_AUTH_HEADER": "Bearer <your-mcp-scoped-key>"
}
}
}
}Replace <your-mcp-scoped-key> with your key. RATION_AUTH_HEADER must include the Bearer prefix.
MCP tools
Tools are grouped by domain. Scope requirements and parameters are defined in the MCP server card. MCP calls do not consume AI credits; rate limits apply instead.
Inventory
search_ingredients, list_inventory, get_cargo_item, add_cargo_item, update_cargo_item, adjust_cargo_item, remove_cargo_item, get_expiring_items, get_expired_items, get_kitchen_summary, inventory_import_schema, preview_inventory_import, apply_inventory_import, import_inventory_csv
Meals
list_meals, match_meals, create_meal, update_meal, delete_meal, toggle_meal_active, clear_active_meals, consume_meal
Planning
get_meal_plan, add_meal_plan_entry, bulk_add_meal_plan_entries, update_meal_plan_entry, consume_manifest_entries, remove_meal_plan_entry
Supply
get_supply_list, add_supply_item, update_supply_item, remove_supply_item, mark_supply_purchased, sync_supply_from_selected_meals, complete_supply_list
Account
get_context, get_billing_summary, get_user_preferences, update_user_preferences
Rate limits: read tools mcp_list (30/min), search mcp_search (20/min), write mcp_write (15/min), supply sync mcp_supply_sync (8/min).