Macropass MCP tools: the nine tools a connected assistant can call

How does authentication work?

Assistants connect over MCP with OAuth 2.1 and PKCE at auth.macropass.app. You approve the connection once and can revoke it in Macropass at any time. Dynamic client registration is supported, so any compliant MCP client can connect without pre-registration. Three scopes exist: macropass.read (today's meals and totals), macropass.write (log, update and delete meals and weigh-ins), and macropass.history.read (list and search history).

MCP endpoint: https://auth.macropass.app/mcp (JSON-RPC 2.0 over HTTPS POST; methods initialize, ping, tools/list, tools/call)
Authorization server metadata: https://auth.macropass.app/.well-known/oauth-authorization-server
Protected resource metadata: https://auth.macropass.app/.well-known/oauth-protected-resource/mcp
Entitlement: An active Macropass trial or subscription; otherwise tools/call returns a payment-required error the client can surface as "subscribe in the app".

What rules apply to every write?

External meal writes must carry the complete text-derived nutrition record: calories plus protein, carbs, fat, fiber and sugar in grams for the whole meal, and one ingredient row with the same six values for every food established in the conversation. Zero means the food genuinely contains none; it is never a placeholder for unknown. Photos, audio and uploaded media are not accepted from external clients. Every write tool accepts an idempotency_key so a retried call does not duplicate a meal. Timestamps are ISO 8601 with a timezone offset.

macropass_log_meal

Log a meal after discussing it with the user in conversation. The assistant estimates calories plus protein, carbs, fat, fiber, and sugar itself, then submits every whole-meal value and a complete nutrition row for every ingredient. Requires macropass.write.

name (string, required): Whole-meal summary, for example "Chicken burrito bowl".
kcal, protein_g, carbs_g, fat_g, fiber_g, sugar_g (number, required): Whole-meal totals; grams for the nutrients.
items (array, required, at least one): One row per ingredient: name (required), qty as the user said it ("180g", "1 cup"), and kcal, protein_g, carbs_g, fat_g, fiber_g, sugar_g (all required per row).
note (string): The user's verbatim phrasing of what they ate; shown in the app as "You said".
assumptions (array of strings): Optional portion or preparation assumptions used for the text-based estimate; shown under "How Macropass estimated".
consumed_at (string): ISO 8601 with offset for when the meal was eaten; defaults to now.
idempotency_key (string): Client-generated key so a retry does not create a duplicate.

User: I had two eggs scrambled in butter and a slice of sourdough.
Assistant: (calls macropass_log_meal with name "Scrambled eggs and sourdough", kcal 390, protein_g 18, carbs_g 28, fat_g 22, fiber_g 2, sugar_g 2, items [eggs, butter, sourdough], assumptions ["Butter counted as 1 tsp"])
Assistant: Logged to Macropass: 390 kcal, 18 g protein.

macropass_get_today

Return meals logged today and their calorie, protein, carbs, fat, fiber, and sugar totals. Connected assistants do not receive private goal or remaining-target context through this tool. Requires macropass.read.

tz_offset_minutes (number): The user's local UTC offset so "today" is bucketed correctly; falls back to the offset the Macropass app last reported, then UTC.

User: What have I eaten so far today?
Assistant: (calls macropass_get_today) Three meals, 1,420 kcal and 96 g protein so far.

macropass_list_history

List meals in a date range. Requires macropass.history.read.

sinceISO, beforeISO (string): ISO 8601 with offset. Both optional.
limit (number): Default 100, maximum 2000.

User: What did I eat last Thursday?
Assistant: (resolves the date in the user's timezone, calls macropass_list_history for that day)

macropass_update_meal

Correct a previously logged meal from conversation text. Text-only metadata changes may omit nutrition. A nutrition correction must resubmit every whole-meal value and the complete ingredient breakdown. Requires macropass.write.

id (string, required): The meal id from get_today, list_history or search_meals.
name, note, consumed_at, assumptions: Optional; omitted fields are left as they are. Pass assumptions as an empty array to clear the list.
kcal, protein_g, carbs_g, fat_g, fiber_g, sugar_g, items: Send all of them together when any nutrition value changes; items replaces the full ingredient list.

User: Yesterday's lunch was actually a double portion.
Assistant: (finds the meal, re-estimates, calls macropass_update_meal with the complete new record)

macropass_delete_meal

Delete a logged meal by id. Requires macropass.write. Deleted meals disappear from the diary and totals immediately.

id (string, required): The meal id.

User: Remove the duplicate coffee from this morning.

macropass_search_meals

Search the user's meal history by free-text query; matches meal names and notes. Requires macropass.history.read.

query (string, required): Free text, for example "burrito".
limit (number): Maximum results.

User: When did I last have sushi, and how many calories was it?

macropass_log_weight

Log a weigh-in. The response includes the seven-day trend delta. Requires macropass.write.

weight_kg (number, required): Body weight in kilograms; convert from pounds before calling.
measured_at (string): ISO 8601 with offset; defaults to now.
note (string): Optional.
idempotency_key (string): Retry safety.

User: I weighed 82.4 kg this morning.

macropass_get_weight_history

Return raw weigh-ins in a range plus the smoothed weekly trend and, if a weight program is set in the app, its projection. Requires macropass.history.read.

sinceISO, beforeISO (string): Optional ISO 8601 bounds.
limit (number): Maximum rows.

macropass_delete_weight

Delete a weigh-in by id. Requires macropass.write.

id (string, required): The weigh-in id.

What is not exposed to external clients?

A connected assistant estimates with its own model. It never uses Macropass photo, voice or AI estimation, and it cannot change goals, save recipes, or export your data. Photo and voice logging stay inside the Macropass app. Goals, periodization, summaries, recipes, meal plans, copy-day, the weight program, export and client management are first-party tools used only by the Macropass apps; a hidden tool name returns the same unknown-tool error as a nonexistent one.

Developer questions

Is there a public REST API?

No. MCP is the integration surface. The nine tools above are the complete external surface.

Which MCP transport does Macropass use?

HTTPS POST with JSON-RPC 2.0 bodies at https://auth.macropass.app/mcp. Notifications receive an empty 202. The server advertises tools only; no resources or prompts.

Can I register my own MCP client?

Yes. Dynamic client registration is supported at auth.macropass.app; the client registers, runs OAuth 2.1 with PKCE, and receives a scoped token. External tokens work only on the MCP endpoint.

Why are all six nutrients required on every ingredient?

So the diary never stores an unknown as zero. A connected assistant submits its best estimate for every value; zero is reserved for foods that genuinely contain none.

Can my client upload a photo?

No. Media upload is first-party only. Describe the meal in text and submit the estimated record.

What happens when the subscription lapses?

tools/call returns a payment-required error (code -32402) until the trial or subscription is active again. tools/list still works.

Which MCP tools does Macropass expose to a connected assistant?