Skip to content
Open
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/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). 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). 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
12 changes: 6 additions & 6 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 All @@ -95,13 +95,13 @@ 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.

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 @@ -120,7 +120,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
8 changes: 4 additions & 4 deletions guides/oauth2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,7 @@ A pre-registered client is granted a fixed scope allowlist at registration. Requ

### Coach scopes

A coach on **Pro Coach tier or higher** (Pro Coach, Head Coach, Business, or Enterprise) can additionally request coach scopes. These unlock the [Coach API](/guides/coach-api) and the coach tools in the [Claude connector](/guides/coach-connector). A coach's OAuth token also carries the athlete-self facet: the same token reads the coach's athlete data on `/v1/athletes/*` and their roster on `/v1/coach/*`, and the route decides which applies.
A coach on **Pro Coach tier or higher** (Pro Coach, Head Coach, Business, or Enterprise) can additionally request coach scopes. These unlock the [Coach API](/guides/coach-api) and the coach tools in the [Saturday connector](/guides/coach-connector). A coach's OAuth token also carries the athlete-self facet: the same token reads the coach's athlete data on `/v1/athletes/*` and their roster on `/v1/coach/*`, and the route decides which applies.

Tier is re-checked on every request. If a coach's tier lapses, the coach scopes stop resolving and the token quietly degrades to athlete-self access rather than erroring, so handle a suddenly empty roster as a billing state, not an outage.

Expand Down Expand Up @@ -303,16 +303,16 @@ Saturday fetches, validates, and caches the document when it first sees your `cl
- The URL must be `https`, use a hostname rather than an IP literal, contain a path, and carry no fragment, userinfo, or dot segments.
- The document's `client_id` field must **exactly match** the document URL.
- `redirect_uris` must be `https` URLs or loopback (`http://localhost` / `http://127.0.0.1`) URIs. Loopback URIs match on any port (RFC 8252).
- CIMD clients are **public clients**: `token_endpoint_auth_method` must be `none` (or absent), and PKCE is mandatory. Confidential CIMD clients (`private_key_jwt`) are not supported.
- CIMD clients are **public clients**, and PKCE is mandatory. The methods the document lists (`token_endpoint_auth_methods_supported` when present, else `token_endpoint_auth_method`, which defaults to `none`) must include `none`, and Saturday then authenticates the client by PKCE alone. When both fields are present, `token_endpoint_auth_method` must be one of the listed methods. A document is refused when its methods lack `none`, when its `token_endpoint_auth_method` is not in its list, or when either field names a shared-secret method (`client_secret_*`).
- `grant_types`, when present, must include `authorization_code`; `response_types`, when present, must include `code`.
- The fetch expects a `200` with a JSON content type within 5 seconds and follows no redirects, so a host that redirects to a `www.` variant fails resolution. Documents over 16 KB are rejected.
- Documents are cached per their `Cache-Control` headers (clamped between 5 minutes and 24 hours, one hour when the header is absent), so metadata changes propagate within that window. Failed fetches and invalid documents are never cached.

A metadata-document client receives the scope set the discovery documents advertise. Saturday advertises support via `"client_id_metadata_document_supported": true` in its Authorization Server Metadata, so spec-compliant MCP clients, including Claude, select CIMD automatically.
A metadata-document client receives the scope set the discovery documents advertise. Saturday advertises support via `"client_id_metadata_document_supported": true` in its Authorization Server Metadata, so spec-compliant MCP clients, including Claude and ChatGPT, select CIMD automatically.

## Discovery (remote MCP connectors)

For the [Claude connector](/guides/coach-connector), clients auto-discover the authorization server, with no manual configuration. Saturday serves the standard metadata documents, derived per-environment from the request host:
For the [Saturday connector](/guides/coach-connector), clients auto-discover the authorization server, with no manual configuration. Saturday serves the standard metadata documents, derived per-environment from the request host:

| Document | Path | Spec |
|----------|------|------|
Expand Down
2 changes: 1 addition & 1 deletion llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Every response carries an `X-Saturday-Data-License` header. Response data is lic

- Full docs: https://docs.saturday.fit
- Coach API guide: https://docs.saturday.fit/guides/coach-api
- Claude connector, athlete and coach tools: https://docs.saturday.fit/guides/coach-connector
- Saturday connector for Claude, athlete and coach tools: https://docs.saturday.fit/guides/coach-connector
- Full LLM context: https://docs.saturday.fit/llms-full.txt
- MCP server: https://api.saturday.fit/mcp
- API root discovery: https://api.saturday.fit/v1/
2 changes: 1 addition & 1 deletion rate-limiting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ if (response.status === 429) {

</CodeGroup>

Athlete-delegated callers (OAuth2 and the Claude connector) also pass through a per-athlete bucket inside the account's bucket, so one heavy user cannot starve the rest. Those 429s carry a longer `Retry-After`. See [OAuth2](/guides/oauth2).
Athlete-delegated callers (OAuth2 and the Saturday connector) also pass through a per-athlete bucket inside the account's bucket, so one heavy user cannot starve the rest. Those 429s carry a longer `Retry-After`. See [OAuth2](/guides/oauth2).

## Daily call limits

Expand Down
Loading