diff --git a/authentication.mdx b/authentication.mdx index c3cd53f..615402c 100644 --- a/authentication.mdx +++ b/authentication.mdx @@ -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). diff --git a/coaching/roster/configuring-alerts.mdx b/coaching/roster/configuring-alerts.mdx index 171e2ab..b6de16f 100644 --- a/coaching/roster/configuring-alerts.mdx +++ b/coaching/roster/configuring-alerts.mdx @@ -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. - 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. ## Payment-failure alerts diff --git a/guides/coach-api.mdx b/guides/coach-api.mdx index 81885f6..9b378b9 100644 --- a/guides/coach-api.mdx +++ b/guides/coach-api.mdx @@ -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: diff --git a/guides/coach-connector.mdx b/guides/coach-connector.mdx index 113957d..76ce8b2 100644 --- a/guides/coach-connector.mdx +++ b/guides/coach-connector.mdx @@ -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. @@ -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. **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). @@ -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. @@ -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" } } } }`. diff --git a/guides/mcp-integration.mdx b/guides/mcp-integration.mdx index 4f1d977..3effadc 100644 --- a/guides/mcp-integration.mdx +++ b/guides/mcp-integration.mdx @@ -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 | - **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. ### Server configuration (partners) @@ -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 | |------|--------------|------| @@ -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`. **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). @@ -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. - **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. diff --git a/guides/oauth2.mdx b/guides/oauth2.mdx index 6dfebae..1aa120c 100644 --- a/guides/oauth2.mdx +++ b/guides/oauth2.mdx @@ -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. @@ -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 | |----------|------|------| diff --git a/llms.txt b/llms.txt index 2b78825..fbc8379 100644 --- a/llms.txt +++ b/llms.txt @@ -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/ diff --git a/rate-limiting.mdx b/rate-limiting.mdx index c305b3a..5f8d56e 100644 --- a/rate-limiting.mdx +++ b/rate-limiting.mdx @@ -88,7 +88,7 @@ if (response.status === 429) { -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