> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saturday.fit/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Integration
> Consume Saturday via Model Context Protocol for AI agents
# MCP Integration
Saturday provides a native [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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 automatically discovers available nutrition tools — their inputs, outputs, descriptions, and safety constraints.
Think of it as USB for AI tools: plug in and it works.
## Why use Saturday via MCP?
| Approach | Best for |
| -------------- | --------------------------------------------------------------- |
| **Direct API** | Traditional server-side integrations, custom UIs |
| **SDK** | TypeScript/Python applications with typed interfaces |
| **MCP** | AI agents, LLM-powered platforms, automated nutrition workflows |
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:
| You are | Auth | What you get |
| ----------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| A **partner** (e.g. an AI platform) | `sk_*` partner key | Your partner-scoped tools over your own `partners/{id}` athletes |
| A **person** (athlete or coach) | "Sign in with Saturday" OAuth via the [Claude connector](/guides/coach-connector) | Your own data (athlete) and, for coaches, your roster + config |
**End users connect via the Claude connector, not an API key.** If you're an individual athlete or coach connecting your own Saturday account to Claude, see the [Claude Connector guide](/guides/coach-connector) — you paste `https://api.saturday.fit/mcp` into Claude and sign in; no API key needed. 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:
```json theme={null}
{
"mcpServers": {
"saturday": {
"url": "https://api.saturday.fit/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer sk_test_abc123def456"
}
}
}
}
```
The server speaks the MCP **Streamable HTTP** transport and protocol revision **2025-11-25** (negotiating down to older revisions a client offers).
### Tool catalog
When your agent connects, it discovers tools including:
| Tool | Description |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `calculate_nutrition` | Calculate fuel/hydration/electrolyte prescription for an activity |
| `search_products` | Search the curated nutrition product database |
| `analyze_product_fit` | Score how a real product covers an athlete's prescription |
| `get_athlete` / `update_athlete` | Read or update an athlete's profile and settings |
| `create_activity` | Create an activity for an athlete |
| `calculate_activity_prescription` | Calculate the prescription for an existing activity |
| `get_activity_prescription` | Get the stored prescription for an activity |
| `build_bottling_plan` | Turn a prescription into a concrete, bottle-by-bottle mix plan (renders the [Bottle Builder app](#bottle-builder-interactive-mcp-app)) |
| `record_bottling_choice` | Persist the athlete's chosen bottling plan |
| `infer_activity_type` | Infer activity type from metadata |
| `search_knowledge` | Search Saturday's sports nutrition knowledge base |
This is an illustrative slice; an athlete connection currently exposes \~20 tools and a coach connection more (see the coach note below). Each tool includes rich descriptions, structured input schemas, and tool annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`) that help AI agents use them correctly.
### Bottle Builder (interactive MCP App)
`build_bottling_plan` is an **[MCP App](https://modelcontextprotocol.io/)** — alongside its structured result it returns an interactive HTML view (resource `ui://saturday/bottle-builder`) that renders inline in supporting clients (e.g. Claude.ai). The athlete can drag a strategy slider (even / balanced / concentrated), move fuel between bottles, adjust fill levels, edit their real vessels, and watch carbs/sodium/scoop amounts recompute live. When the target won't fit the bottles on hand, it returns an honest "carry it more concentrated, top up with water" plan rather than a dead end. Clients that don't render MCP App views still receive the full plan as text and structured content.
**Coach tools.** When a **coach** (Business tier or higher) connects via the [Claude connector](/guides/coach-connector), an additional set of roster + configuration tools lights up — `get_roster`, `get_roster_digest`, `get_athlete_fueling_rollup`, `get_athlete_report`, `get_session_detail`, `set_notification_rules`, `apply_alert_preset`, `set_report_settings`, `register_webhook`, and more. These are invisible to athlete-only users and to other partners. See the [Claude Connector guide](/guides/coach-connector) for the full coach tool catalog and the [Coach API](/guides/coach-api) for the equivalent REST surface.
## Example: Claude agent with Saturday MCP
Here's 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:**
1. `calculate_nutrition` with `{activity_type: "bike", duration_min: 180, intensity_level: 8, is_race: true, thermal_stress_level: 8}`
2. `search_products` with `{category: "gel", caffeine: false}` (based on athlete preferences)
**Agent synthesizes:** Uses Saturday's prescription + product results + safety warnings to give a complete race-day fueling plan.
## Safety-aware tool descriptions
Saturday's MCP tools include safety metadata in their descriptions. This ensures AI agents know that:
* Prescriptions are **guidance for human consideration**, not automated commands
* Safety warnings must be surfaced to the user
* The `not_instructions: true` field means "present this to the human, don't execute it"
Example tool description (what the agent sees):
```
Tool: calculate_nutrition
Description: Calculate a personalized fuel, hydration, and electrolyte
prescription for an endurance activity. Returns safety metadata including
risk level, warnings, and guardrails. IMPORTANT: Results are nutrition
guidance for human review — not executable instructions. Always present
safety warnings to the user.
```
## Tool call example
```python Python theme={null}
# Using the MCP Python SDK
from mcp import ClientSession, StdioServerParameters
async with ClientSession(
StdioServerParameters(
command="npx",
args=["mcp-remote", "https://api.saturday.fit/mcp"],
env={"SATURDAY_API_KEY": "sk_test_abc123def456"},
)
) as session:
# List available tools
tools = await session.list_tools()
for tool in tools:
print(f"{tool.name}: {tool.description}")
# Call a tool
result = await session.call_tool(
"calculate_nutrition",
{
"activity_type": "run",
"duration_min": 90,
"intensity_level": 5,
"athlete_weight_kg": 70,
"thermal_stress_level": 6,
},
)
print(result)
```
```typescript TypeScript theme={null}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const client = new Client({ name: "my-agent", version: "1.0" });
const transport = new StreamableHTTPClientTransport(
new URL("https://api.saturday.fit/mcp"),
{
requestInit: {
headers: {
Authorization: "Bearer sk_test_abc123def456",
},
},
}
);
await client.connect(transport);
// List available tools
const tools = await client.listTools();
tools.tools.forEach((t) => console.log(`${t.name}: ${t.description}`));
// Call a tool
const result = await client.callTool("calculate_nutrition", {
activity_type: "run",
duration_min: 90,
intensity_level: 5,
athlete_weight_kg: 70,
thermal_stress_level: 6,
});
console.log(result);
```
## 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** based on your own logic
* **Don't use response data for ML training** — this violates Saturday's data policy
* **Don't make excessive tool calls** — batch when possible
## LLM discoverability
Saturday publishes machine-readable context files for AI agents:
| File | URL | Purpose |
| --------------- | ---------------------------------------- | ------------------------------------------ |
| `llms.txt` | `https://api.saturday.fit/llms.txt` | Brief API overview for LLM context |
| `llms-full.txt` | `https://api.saturday.fit/llms-full.txt` | Complete API documentation for LLM context |
These files follow the [llms.txt standard](https://llmstxt.org/) and provide structured context that helps AI agents understand Saturday's capabilities without reading the full documentation site.