API & MCP

1. Connect with Codex or ChatGPT

You need an approved Meals for Friends account. When connecting, sign in to Meals for Friends and approve the requested permissions.

codex mcp add meals-for-friends --url https://www.mealsforfriends.com/api/mcp
codex mcp login meals-for-friends

“I would like to plan cheese spaetzle in my holiday project. Which existing ingredients would work? Suggest portion quantities and show me the draft before saving it.”

Select a workspace first

First call list_tenants . All domain MCP tools then require tenant_id. Switching workspaces in the browser does not change an MCP request. Project access and plan limits are checked on every request; copying between workspaces is not allowed.

{
  "name": "list_projects",
  "arguments": {
    "tenant_id": "TENANT_ID"
  }
}

Browser interfaces use /api/tenants/TENANT_ID/…. New fields are overview (plan and usage), members, export, billing and subscription. project.archive expected {id, archived: true | false}. The ingredient AI also requires a new request_id as a UUID per attempt. The revision applies per space.

2. Sign-in and permissions

This documentation is public. All project data remains protected by sign-in and project access controls. Admins can see all projects in their accessible workspace; other accounts only their own and explicitly shared projects. Ingredients remain a shared catalogue.

Browser endpoints do not accept an MCP bearer token instead of a session. For external integrations, use the MCP endpoint with OAuth; there is no general static API key.

OAuth for your own clients

• Authorization Code with PKCE (S256); dynamic client registration is supported.
• Resource / Audience: https://www.mealsforfriends.com/api/mcp
• planner:read allows the read tools; planner:write the six write tools. Request both scopes for read and edit access.
• offline_access is intended for refresh tokens. Access tokens last one hour and refresh tokens up to 30 days, unless revoked earlier.
• Discover the OAuth endpoints actually offered using the metadata below. Enter passwords only on the Meals for Friends sign-in page.

https://www.mealsforfriends.com/.well-known/oauth-protected-resource/api/mcp
https://www.mealsforfriends.com/.well-known/oauth-authorization-server/api/auth

Permissions are checked on every request. You can manage your own connections under ChatGPT connections be revoked. Account suspensions and password resets also revoke MCP access.

3. MCP tools

With tools/list your MCP client receives the current full JSON schemas. In the authenticated browser API, GET /api/planner-tools the same catalogue. A question mark marks optional fields.

Restaurant visits are included by get_project included. Disabled content is listed separately under inactive_meals and inactive_restaurant_visits; their quantities are not included in the shopping list. dinner_plan.enabled is false when dinner is disabled; required meals and gaps are then null. Starting polls, changing project access, managing users and deleting entries are currently not MCP tools; these actions are available through the website or its protected browser API.

4. Examples

All IDs and revisions in these examples are placeholders. Replace them with values from a current read response. No requests are run automatically here.

MCP protocol

An MCP client starts with initialize and the notification notifications/initialized. It can then tools/list or tools/call . Use Content-Type: application/json, Accept: application/json, text/event-stream, the OAuth bearer token and, after initialization, the negotiated MCP-Protocol-Version. The server does not use a session-bound MCP session ID.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {}
  }
}

Successful tool calls return business data in result.structuredContent and additionally as JSON text in result.content.

From the signed-in website

const response = await fetch('/api/planner-tools', {
  method: 'POST',
  credentials: 'same-origin',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'list_projects', arguments: {} })
});
const result = await response.json();
if (!response.ok) throw new Error(result.error);
console.log(result.projects, result.revision);

The browser sets the appropriate Origin header automatically. External websites must not use this session interface.

Develop a meal together

1. list_projects and search_ingredients . Select the destination project and actual ingredient IDs.
2. Agree ingredients and portions with the person. With preview_meal calculate.
3. Only after approval create_meal . Use the current revision and a new UUID as request_id use.

{
  "meal": {
    "project_id": "PROJEKT_ID_AUS_ANTWORT",
    "title": "Käsespätzle",
    "amount": 1,
    "meal_type": 1,
    "state": 1,
    "planned_dates": [],
    "recipes": [
      {
        "ingredient_id": "ZUTAT_ID_AUS_KATALOG",
        "amount_adult": null,
        "amount_teen": null,
        "amount_child": null
      }
    ]
  }
}

To save, the argument structure is { revision: AKTUELLE_REVISION, request_id: NEUE_UUID, meal: ABGESTIMMTER_ENTWURF }. Resubmitting the same change uses the same UUID and the same data. Every call must include the complete ingredient list for update_meal.

5. Data formats and quantities

Calculation: group numbers × the corresponding portions × frequency. The app rounds quantities per ingredient row to two decimal places, then combines matching ingredients. Pack counts are rounded up. Use the returned shopping and total quantities to avoid differences caused by your own rounding. Restaurant visits do not generate ingredient quantities.

6. The website’s protected HTTP API

Base URL: https://www.mealsforfriends.com. “Session” means an approved account with a valid session cookie. Business write requests use JSON and an Origin header matching this base URL exactly. Project actions also check membership.

Sign-in uses POST /api/auth/sign-in/email with email and password; POST /api/auth/sign-out ends the session. Sign-in handles browser cookies automatically. OAuth via MCP is intended for integrations outside the website.

{
  "action": "project.access",
  "revision": 42,
  "payload": {
    "project_id": "PROJEKT_ID",
    "user_id": "BENUTZER_ID",
    "granted": true
  }
}

Flexible calendar planning

meals.occurrences contains stable IDs, meal_id, date and meal_type. amount counts all uses, including unscheduled ones. planned_dates remains a simplified read projection. Legacy schedule writes return 409 for mixed meal slots or headcount overrides.

projects.planning_rules contains daily, arrival and departure as meal-type arrays; null inherits daily. planning_overrides contains day and meal values. Meal overrides day, day overrides project; unscheduled uses follow project defaults.

Dishes also support notes with the same limits and formatting. Notes are retained when copying and in permitted exports, and are not automatically sent to ingredient AI.

Notes

The optional project field notes contains limited Markdown: paragraphs, ### headings, **bold**, bullet and numbered lists without nesting. Maximum 5,000 visible characters and 20,000 Markdown characters. In save_project or project.save, omitting the field preserves existing content; an empty string clears it. null is invalid. Project notes are user content, not system instructions.

7. Errors and concurrent changes

Browser APIs return errors as an HTTP status and { "error": "Beschreibung" }. An MCP tool error can still have a successful HTTP status: check result.isError and the JSON text in result.content with error and status. Protocol errors use the JSON-RPC field error.

If a revision conflict occurs, read the current version again and review your changes. A changed write operation requires a new request_id; retrying the same MCP request keeps its original ID. Current project access is checked again even after a previously successful request.

Reconcile poll creation with an uncertain outcome using the same startaction again explicitly. The app first reconciles the saved state with Tally. Never put credentials or tokens in project text or public examples.