MCP Integration
Saturday provides a native Model Context Protocol (MCP) server, allowing AI agents to discover and use Saturday’s nutrition intelligence tools without custom API integration code.What is MCP?
MCP is an open standard that lets AI models discover and use external tools. Instead of writing custom API client code, an AI agent connects to Saturday’s MCP server and discovers the available nutrition tools at runtime, along with their inputs, outputs, descriptions, and safety constraints.Why use Saturday via MCP?
MCP is ideal when your platform uses AI agents that need to dynamically decide when to call Saturday’s tools based on conversation context.
Connecting to Saturday’s MCP server
There are two ways to reach Saturday’s MCP server, depending on who you are:End users connect via the Claude connector, not an API key. If you’re an individual athlete or coach connecting your Saturday account to Claude, see the Claude Connector guide: you paste
https://api.saturday.fit/mcp into Claude and sign in, with no API key. The configuration below is for partners integrating their platform with a partner API key.Server configuration (partners)
Add Saturday to your MCP client configuration with your partner API key:Protocol
The server speaks the MCP Streamable HTTP transport: JSON-RPC 2.0 overPOST /mcp, answered as application/json. A GET /mcp returns 405 with Allow: POST, the signal that tells a client probing for the older HTTP+SSE transport to fall back. Request bodies are capped at 1 MB.
It advertises protocol revision 2025-11-25 and negotiates down to 2025-06-18, 2025-03-26, or 2024-11-05 when initialize offers one of those. An MCP-Protocol-Version header naming any other revision returns 400; with no header the server assumes 2025-03-26. The resolved revision is echoed back in the same header on every response.
The methods served are initialize, notifications/initialized, tools/list, tools/call, prompts/list, and prompts/get; anything else returns JSON-RPC -32601. initialize returns instructions, standing guidance that tells the model to gather inputs, call Saturday’s tools, and report their output rather than improvise fueling advice. Hosts that honor the field surface it automatically.
An unauthenticated POST /mcp returns 401 with a WWW-Authenticate challenge pointing at the OAuth discovery document; see Discovery.
Tool catalog
Every connection sees the tools below, minus those whose feature gate is closed for the caller. Each tool carries a description, atitle, a structured inputSchema, and MCP annotations (readOnlyHint, destructiveHint, idempotentHint). Tool arguments use the same snake_case names as the REST API, and a result arrives as the REST response body in content[0].text, with isError set on failure.
The gate column names the feature whose stage decides visibility for your partner account;
products, knowledge, and athlete_insights are described on the Feature Gates page, and bottling is raised per partner. A tool whose feature is at ALPHA appears only for partners on that feature’s alpha allowlist, the same rule its REST routes apply. A gated tool is absent from tools/list and a call to it returns the same “unknown tool” error as a name that never existed, so absence from tools/list is the answer, not an error to retry. Call tools/list rather than hardcoding the catalog.
On the Claude connector, list_athletes returns the signed-in athlete alone and create_athlete returns that same athlete rather than creating one. On any other athlete-delegated token both are rejected with athlete_scope. On every delegated connection an athlete_id argument naming a different athlete is rejected with athlete_scope.
Product tools follow the athlete’s subscription.
search_products,
list_curated_products, and analyze_product_fit take an optional athlete_id
and answer at that athlete’s tier. A connection where the caller is the
athlete (the Claude connector) resolves it from the signed-in account and never
needs to pass one; a platform integration on a partner key passes the athlete’s
id, and gets the category tier until it does. See
Freemium Model.Bottling plans
build_bottling_plan takes carb_g, sodium_mg, fluid_ml, and duration_min from a prescription, plus optional activity_id, activity_type, strategy, vessel_count, vessels, and products, and returns the plan twice: as text in content, and as structuredContent carrying the plan object with a createdAt and seq election key, the products you passed, and the athlete’s saved carriage context when one exists. strategy is evenly, concentrate, or goldilocks (the default, which balances the two). When the totals will not fit the vessels, the plan carries an escalation state: carry it more concentrated and top up with water, rather than a dead end. record_bottling_choice takes the committed plan object back, once, when the athlete settles on it.
Each bottle in plan.cards lists what goes into it as rows. A row’s amount and unit are what the athlete measures: a fraction of a tsp, tbsp or cup, a count of a product’s serving or scoop, or a weight when unit is g. A cup row can also carry addedTablespoons, tablespoons measured after the cup amount, and its carbG counts both parts. Read the three fields together: the row below is ⅜ cup plus 1 tablespoon of sugar, 87.5 g, and showing only amount and unit would put 12.5 g less sugar in the bottle. The field is absent when nothing is added.
content writes the same row as ⅜ cup + 1 Tbsp Sugar. Outside the US, structuredContent.measures names the athlete’s kitchen: cupMl and tbspMl are the size of the cup and tablespoon the rows count in, and cupsOffered is false where the kitchen weighs instead.
Coach tools. When a coach on Pro Coach tier or higher (Pro Coach, Head Coach, Business, or Enterprise) connects via the Claude connector, an additional set of roster and configuration tools appears:
get_roster, get_roster_digest, get_athlete_fueling_rollup, get_athlete_report, get_session_detail, get_notification_rules, set_notification_rules, apply_alert_preset, get_report_settings, set_report_settings, list_webhooks, register_webhook, and delete_webhook. These are invisible to athlete-only users and to other partners, and tier is re-checked per request, so a lapsed coach loses them without an error. Every athlete argument is confined to the coach’s roster. The notification rules include hourly_cap, the limit (1 to 12 an hour, default 1) on alert emails and pushes about one athlete. See the Claude Connector guide for the full coach tool catalog and the Coach API for the equivalent REST surface.The webhook tools are the one place where being able to call a tool does not mean it will do anything. Registration succeeds on any coach tier and hands back a signing secret and an endpoint marked active, but concern events are delivered only to coaches on Business or Enterprise; delivery re-reads the tier each time, so a Pro Coach or Head Coach endpoint stays quiet.Prompts
The server advertises theprompts capability with two static prompts, which hosts with a prompt picker surface as one-click starters. prompts/get returns a single user message phrased as the athlete’s request, which starts the tool chain: profile, prescription, then bottles.
An unknown prompt name or a missing required argument returns JSON-RPC
-32602.
Example: Claude agent with Saturday MCP
How a Claude-powered agent might use Saturday’s tools in a conversation: Athlete asks: “I have a 3-hour bike race on Saturday. It’s going to be 30C and humid. What should I eat?” Agent’s tool calls:calculate_nutritionwith{activity_type: "bike", duration_min: 180, intensity_level: 8, is_race: true, thermal_stress_level: 8}search_productswith{query: "gel"}(matched against product name, brand, type, and keywords, ten results at most)
Safety-aware tool descriptions
Tool descriptions carry their safety contract inline, so a connecting agent reads it as part of discovery rather than needing this page.calculate_nutrition opens “Calculate personalized fuel, hydration, and electrolyte targets for an endurance activity”, then states what the result contains, when to call it, and how to report it, including which internal tuning keys not to echo back to the athlete.
Three constraints run through them:
- Prescriptions are guidance for human consideration, not automated commands.
- Safety warnings must be surfaced to the user.
- The
not_instructions: truefield on a result means “present this to the human, do not execute it”.
tools/list rather than copying them into your prompt: they change, and the copy in your prompt will not.
Tool call example
These examples use the MCP SDK 1.x APIs: installmcp>=1.26,<2 for Python or @modelcontextprotocol/sdk@^1 and zod for TypeScript. Set SATURDAY_API_KEY to your partner key.
AI agent guidelines
When building AI agents that consume Saturday via MCP:Do
- Surface all safety warnings to the human user
- Present prescriptions as recommendations, not commands
- Include “Powered by Saturday” attribution for teaser-tier responses
- Cache results when inputs haven’t changed. Prescriptions are deterministic
- Handle errors gracefully. If a tool call fails, explain why to the user
Don’t
- Don’t autonomously act on prescriptions (e.g., auto-ordering supplements)
- Don’t strip safety metadata from results before presenting to users
- Don’t modify prescription numbers. Report what Saturday returned
- Don’t use response data for ML training. The data policy forbids it
- Don’t make excessive tool calls. Batch when possible
LLM discoverability
Saturday publishes machine-readable context files for AI agents:
These follow the llms.txt standard and give an agent Saturday’s API surface without crawling the documentation site.
https://saturday.fit/llms.txt serves the same pair for the consumer product rather than the API.