Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion authentication.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Saturday has three authentication methods, one per principal type:
|--------|----------|--------------|
| **Partner API Key** | Server-to-server partner integration | `sk_*` Bearer token in the `Authorization` header |
| **Coach API Key** | A coach's own scripts against their roster | `cp_*` Bearer token in the `Authorization` header |
| **OAuth2** | Athlete- or coach-delegated access, including the Claude connector | Authorization code flow with PKCE |
| **OAuth2** | Athlete- or coach-delegated access, including the Saturday connector for AI assistants | Authorization code flow with PKCE |

Most partner integrations start with API keys. Add OAuth2 when you need athletes or coaches to connect their existing Saturday accounts. Coaches automating against their roster use a coach API key, covered in the [Coach API](/guides/coach-api).

Expand Down
2 changes: 1 addition & 1 deletion coaching/roster/configuring-alerts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ When an athlete belongs to more than one group, Saturday does not pick a group a
- **Combinations.** Two-trigger AND rules, for example "ping me only when sodium is short and there is a symptom in the same session". Both legs must be session-level triggers; the sleep trend and the gone-quiet flag describe a window rather than a single session, so they cannot be combined.

<Note>
A rule can also carry a **webhook** channel, which the portal marks as pending rather than dropping. Managing an organization's webhooks is a Business and Enterprise capability. For programmatic alerting, use the [Coach API](/guides/coach-api) or the [Claude connector](/guides/coach-connector), which read and write the same rule model the GUI does.
A rule can also carry a **webhook** channel, which the portal marks as pending rather than dropping. Managing an organization's webhooks is a Business and Enterprise capability. For programmatic alerting, use the [Coach API](/guides/coach-api) or the [Saturday connector](/guides/coach-connector), which read and write the same rule model the GUI does.
</Note>

## Payment-failure alerts
Expand Down
2 changes: 1 addition & 1 deletion guides/activities.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ Returns the most recently calculated prescription for this activity, wrapped wit
GET /v1/athletes/{athlete_id}/activities/{activity_id}
```

The activity response carries the stored prescription inline. An athlete's synced activity read through the [Claude connector](/guides/coach-connector) can also carry `source_attributions`, the credit its data source requires; see [Data source credits](/guides/attribution#data-source-credits).
The activity response carries the stored prescription inline. An athlete's synced activity read through the [Saturday connector in Claude](/guides/coach-connector) can also carry `source_attributions`, the credit its data source requires; see [Data source credits](/guides/attribution#data-source-credits).

## Listing activities

Expand Down
2 changes: 1 addition & 1 deletion guides/attribution.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ device model is unknown. The array is absent when no source behind the data requ

| Surface | Where `source_attributions` appears |
|---|---|
| The athlete's activities through the [Claude connector](/guides/coach-connector) | Each activity from `GET /v1/athletes/{athlete_id}/activities`, `GET` and `PATCH .../activities/{activity_id}`, and the `list_activities` and `get_activity` tools |
| The athlete's activities through the [Saturday connector in Claude](/guides/coach-connector) | Each activity from `GET /v1/athletes/{athlete_id}/activities`, `GET` and `PATCH .../activities/{activity_id}`, and the `list_activities` and `get_activity` tools |
| Insights | `GET /v1/athletes/{athlete_id}/insights` and the `get_athlete_insights` tool, for every activity analyzed |
| [Coach API](/guides/coach-api#data-sources) and coach tools | Each rollup and session-detail session, the AI report, and each roster and digest row |
| [Coach webhooks](/guides/coach-api#webhooks) | Each coach concern event, for the sessions it is about |
Expand Down
2 changes: 1 addition & 1 deletion guides/coach-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Two ways to authenticate as a coach. Both resolve to the same coach identity and
| Method | Token | Best for |
|--------|-------|----------|
| **Coach API key** | `cp_live_…` / `cp_test_…` (Bearer) | Scripts, automations, server-to-server |
| **OAuth2 (coach scopes)** | OAuth2 access token (Bearer) | The Claude.ai connector / user-delegated apps |
| **OAuth2 (coach scopes)** | OAuth2 access token (Bearer) | The Saturday connector for AI assistants / user-delegated apps |

Coach API keys are minted in the [coach portal](https://coach.saturday.fit) under **[Admin → API Keys](https://coach.saturday.fit/admin/api-keys)**. Pass the key as a Bearer token:

Expand Down
16 changes: 9 additions & 7 deletions guides/coach-connector.mdx
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: 'Claude Connector'
title: 'Saturday Connector'
description: 'Connect Saturday to Claude: one connector, athlete and coach tools'
sidebarTitle: 'Claude Connector'
sidebarTitle: 'Saturday Connector'
icon: 'plug'
---

# Saturday Claude Connector
# Saturday Connector

Saturday publishes a remote MCP connector for [Claude](https://claude.ai). There is one connector and one URL; which tools appear depends on who signs in.

Expand All @@ -22,7 +22,9 @@ In Claude, add a custom connector pointing at:
https://api.saturday.fit/mcp
```

Claude auto-discovers Saturday's authorization server (RFC 9728 / RFC 8414 discovery), walks you through **"Sign in with Saturday,"** and shows a branded consent screen. A coach granting access sees an explicit disclosure that Claude will be able to read their athletes' fueling data and manage their alert settings, and will never write to an athlete's training data.
Custom connectors work on every Claude plan and, once added, on every Claude app ([Anthropic's guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)).

The assistant auto-discovers Saturday's authorization server (RFC 9728 / RFC 8414 discovery), walks you through **"Sign in with Saturday,"** and shows a branded consent screen. A coach granting access sees an explicit disclosure that the assistant will be able to read their athletes' fueling data and manage their alert settings, and will never write to an athlete's training data.

<Note>
**Subscriber wall.** Only an active Saturday subscriber can complete the connect flow. A non-subscriber sees a "subscription required" page carrying a **Subscribe** link to plans and a **"Use a different account"** option for re-authenticating after signing in with the wrong account. Nothing is written to their account. A lapsed subscriber loses access within about an hour, on the next token refresh (access tokens live one hour).
Expand All @@ -34,7 +36,7 @@ The connector speaks the MCP Streamable HTTP transport (`POST /mcp`) and protoco

## Athlete tools

When an athlete connects, Claude can read and write that athlete's Saturday data. Athlete tools operate strictly on the signed-in athlete; there is no athlete selector. The full catalog is in [MCP Integration](/guides/mcp-integration#tool-catalog), less `get_fueling_profile`, which is for partner platforms. Highlights:
When an athlete connects, the assistant can read and write that athlete's Saturday data. Athlete tools operate strictly on the signed-in athlete; there is no athlete selector. The full catalog is in [MCP Integration](/guides/mcp-integration#tool-catalog), less `get_fueling_profile`, which is for partner platforms. Highlights:

- `get_athlete`, `update_athlete` read and update the athlete's profile.
- `list_activities`, `get_activity`, `create_activity` manage the athlete's activities.
Expand Down Expand Up @@ -87,11 +89,11 @@ The rules carry `hourly_cap` (`{ enabled, per_hour }`), the limit on emails, and

## Configuring a roster in one conversation

The connector writes config as well as reading data. A coach can describe their monitoring philosophy in plain English and let Claude configure the whole roster:
The connector writes config as well as reading data. A coach can describe their monitoring philosophy in plain English and let the assistant configure the whole roster:

> *"Only ping me when sodium is under 60% on long rides for my elite group; bundle everyone else into a Friday digest, and POST concern alerts to my system."*

Claude translates that into:
The assistant translates that into:

1. `apply_alert_preset` `{ scope: "overall", preset: "balanced" }` sets a baseline for everyone.
2. `set_notification_rules` `{ scope: "group", scope_id: "grp_elite", rules: { notification_rules: { under_fuel: { enabled: true, urgent_threshold: 0.6, channels: ["webhook"], cadence: "realtime" } } } }`.
Expand Down
14 changes: 7 additions & 7 deletions guides/mcp-integration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,10 @@ 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 the athletes under your partner account |
| A **person** (athlete or coach) | "Sign in with Saturday" OAuth via the [Claude connector](/guides/coach-connector) | Your data (athlete) and, for coaches, your roster + config |
| A **person** (athlete or coach) | "Sign in with Saturday" OAuth via the [Saturday connector](/guides/coach-connector) | Your data (athlete) and, for coaches, your roster + config |

<Note>
**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](/guides/coach-connector): 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.
**End users connect via the Saturday connector, with no API key.** If you're an individual athlete or coach connecting your Saturday account to Claude, see the [Saturday Connector guide](/guides/coach-connector): you add `https://api.saturday.fit/mcp` in Claude and sign in. The configuration below is for **partners** integrating their platform with a partner API key.
</Note>

### Server configuration (partners)
Expand Down Expand Up @@ -68,7 +68,7 @@ An unauthenticated `POST /mcp` returns `401` with a `WWW-Authenticate` challenge

### Tool catalog

Every connection sees the tools below, minus those whose feature gate is closed for the caller. Each tool carries a description, a `title`, 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.
Every connection sees the tools below, minus those whose feature gate is closed for the caller. Each tool carries a description, a `title`, a structured `inputSchema`, and MCP annotations (`readOnlyHint`, `destructiveHint` and `openWorldHint` on every tool, `idempotentHint` where it applies). 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.

| Tool | What it does | Gate |
|------|--------------|------|
Expand Down Expand Up @@ -96,15 +96,15 @@ Every connection sees the tools below, minus those whose feature gate is closed

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](/guides/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.

`get_fueling_profile` is listed on partner connections, on a partner key or a partner's athlete-delegated token, and has no feature gate. The Claude connector does not list it: there the caller is the athlete, who reads their account through `get_athlete`. Its result's `sharing` is `on`, `off`, or `not_linked`, and only `on` carries answers; see [Reading an athlete's fueling profile](/guides/fueling-profile).
`get_fueling_profile` is listed on partner connections, on a partner key or a partner's athlete-delegated token, and has no feature gate. The Saturday connector in Claude does not list it: there the caller is the athlete, who reads their account through `get_athlete`. Its result's `sharing` is `on`, `off`, or `not_linked`, and only `on` carries answers; see [Reading an athlete's fueling profile](/guides/fueling-profile).

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`.
On the Saturday connector in Claude, `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`.

<Note>
**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
athlete (the Saturday connector in Claude) 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](/guides/freemium-model#the-product-catalog).
Expand All @@ -123,7 +123,7 @@ Each bottle in `plan.cards` lists what goes into it as `rows`. A row's `amount`
Kitchen sugar follows the athlete's carb measure from their Saturday profile (cups, cups plus a tablespoon, tablespoons, or grams); a call without an athlete reads cups. The text in `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.

<Note>
**Coach tools.** When a **coach on Pro Coach tier or higher** (Pro Coach, Head Coach, Business, or Enterprise) connects via the [Claude connector](/guides/coach-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](/guides/coach-connector) for the full coach tool catalog and the [Coach API](/guides/coach-api) for the equivalent REST surface.
**Coach tools.** When a **coach on Pro Coach tier or higher** (Pro Coach, Head Coach, Business, or Enterprise) connects via the [Saturday connector](/guides/coach-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 [Saturday Connector guide](/guides/coach-connector) for the full coach tool catalog and the [Coach API](/guides/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.
</Note>
Expand Down
Loading
Loading