# Health Access MCP, the whole thing in one file

Written for an AI that has to install and use Health Access MCP without reading any other page. Version of this file: 2026-10-25. Canonical URL: https://healthaccessmcp.com/llms-full.txt

## 1. What it is

Health Access is middleware. It does the one thing Apple requires a phone app for, writing your workouts and vitals as JSON into a folder you pick, and then it gets out of the way. Your AI reads that folder, through the MCP or just as files. If it writes you a plan, one tap puts it on your Watch.

Three parts:

- The iPhone app, "Health Access" (iOS 17 or later). Reads HealthKit, writes `workouts/*.json`, `vitals/*.json`, `index.json` and `plans/*.status.json` into a folder the user picked. Puts plans onto the Apple Watch through WorkoutKit. No server, no account. Pre-release: built from source today, TestFlight planned.
- `healthaccess-mcp`, an MCP server over stdio (Rust, MIT). Reads the folder, writes `plans/<id>.json`, a small presence file under `mcp/clients/` and the two rating fields of a workout, nothing else. Thirteen tools, two resource types. Live.
- `healthaccess`, a command line with the same views (`list`, `show`, `summary`, `rate`, `plan push|status|list`, `doctor`). Live.

The folder can be anywhere the iOS Files app can open: iCloud Drive, Dropbox, Google Drive, OneDrive, Proton Drive, SMB/NAS, On My iPhone. The one rule: the computer where the AI runs must see the same folder. The app does not know the path on the computer; the user does.

What is planned, not live, as of 2026-10-26: the app on the App Store (it is in testing), a Homebrew tap and a crates.io package, the public source repository.

Project history: the codename was "Tide" until 2026-10-25. Old identifiers are accepted forever as aliases (section 13). The repository directory on disk may still be called `tide`.

## 2. The order of things

Once, about five minutes, the user:
1. Installs the app.
2. Picks a folder (any Files provider) that syncs to the computer where the AI runs.
3. Allows Health access (read only, chosen types) and notifications (one kind only: "Your AI wrote S27", when a plan file appears).
4. Gives the MCP to the AI: pastes one paragraph, the AI sets itself up from this file.

Every workout, nobody:
1. The user ends a workout on the Watch.
2. Next time the phone is unlocked, the app writes `workouts/<date>_<time>_<Activity>_<uuid8>.json`: distance, time, heart rate every few seconds, every interval with its name, every length with stroke and SWOLF. Vitals land once a day.
3. The folder syncs to the computer.
4. The AI reads it. No app on that side.

Sometimes, one tap, the user:
1. Rates the session on the Watch when it asks (effort 1 to 10). Apple exports the score and the app picks it up as `effort_source: apple`. The app itself never asks for a rating.
2. Taps "Put on Watch" when the AI has written a plan.

Whenever asked, the AI:
1. Reads sessions, vitals and trends through the MCP, or reads the JSON directly.
2. Writes `plans/<id>.json` through `push_plan`. It shows up in the app within about a minute.
3. Can work without the MCP: the folder holds plain JSON and `briefing.md`.

## 3. Install the server

Nothing to install by hand. The server is published on npm as `healthaccess-mcp` with prebuilt binaries for macOS (Apple silicon and Intel), Linux (x64, arm64) and Windows (x64). It needs Node.js 18 or newer for `npx`:

```sh
npx -y healthaccess-mcp --check     # downloads the server once, prints the folder it found, exits
```

The same package carries the command line: `npx -y -p healthaccess-mcp healthaccess doctor`, or `npm install -g healthaccess-mcp` for both `healthaccess-mcp` and `healthaccess` on the PATH. The npm binaries contain no network code.

From source instead (Rust stable 1.99 or newer, repository access): `cargo install --path mcp --locked` and `cargo install --path cli --locked`, then use `healthaccess-mcp` wherever this file says `npx -y healthaccess-mcp`.

## 4. The folder

The server finds the Health Access folder on its own. Resolution order: `--dir` on the command line, the environment variable `HEALTHACCESS_DIR`, `dir` in `~/.config/healthaccess/config.toml`, then a search: iCloud Drive first (`~/Library/Mobile Documents/com~apple~CloudDocs` on a Mac, `%USERPROFILE%\iCloudDrive` on Windows), then the other file providers (`~/Library/CloudStorage/*`, `~/Dropbox`, `~/Google Drive`, `~/OneDrive*`, `~/Box`), then `~/Documents`. A Health Access folder is a directory with an `index.json` of schema `healthaccess.index.v1` and a `workouts/` directory. When several exist, the one whose `index.json` changed last wins and the others are logged to stderr.

`npx -y healthaccess-mcp --check` prints the folder and where it came from ("found on this computer", "--dir", "config.toml"). If it finds nothing, ask the user where the folder is and pass `--dir "<absolute path>"`. The app's setup message names the folder and, for iCloud Drive, its usual Mac path. Check a folder by hand with `ls "<folder>/workouts"`; on iCloud Drive, opening the folder in Finder downloads files that are only in the cloud.

Optional config file:

```toml
# ~/.config/healthaccess/config.toml
dir = "/Users/<user>/Library/Mobile Documents/com~apple~CloudDocs/Health Access"   # optional, skips the search
zone_bounds = [133, 146, 158, 170]   # optional: upper bounds of heart-rate zones 1 to 4, bpm. Without it the bounds are
                                     # estimated from the age in profile.json (max HR 208 - 0.7 x age; 72/79/86/92 % of max)
```

## 5. Register the server with the client

Transport: stdio. Command: `npx`. Arguments: `-y`, `healthaccess-mcp`, and optionally `--dir "<folder>"`. No environment variables needed. If a GUI client reports `spawn npx ENOENT`, it does not see the shell PATH: use the absolute path that `which npx` prints as the command.

Claude Code:

```sh
claude mcp add --scope user healthaccess -- npx -y healthaccess-mcp
# --scope user = all projects; omit for the current project only
```

Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`; Claude menu, Settings, Developer, Edit Config; restart Claude Desktop after saving):

```json
{
  "mcpServers": {
    "healthaccess": {
      "command": "npx",
      "args": ["-y", "healthaccess-mcp"]
    }
  }
}
```

Cursor (`~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` in a project): the same JSON as Claude Desktop.

LM Studio (0.3.17 or later; Program tab, Install, Edit mcp.json): the same JSON as Claude Desktop.

Goose (`goose configure`, Add Extension, Command-line Extension; or `~/.config/goose/config.yaml`):

```yaml
extensions:
  healthaccess:
    name: Health Access
    type: stdio
    cmd: npx
    args: ["-y", "healthaccess-mcp"]
    enabled: true
    timeout: 300
```

Claude Code project file `.mcp.json` (project scope): the same JSON as Claude Desktop.

ChatGPT: cannot launch a local stdio server. It connects to remote HTTPS MCP servers only, on some plans. Use the files instead: upload `briefing.md` or a workout JSON, or paste the output of `npx -y -p healthaccess-mcp healthaccess summary --weeks 4`. Do not expose the server through a public tunnel without authentication.

Verify: `claude mcp list` (Claude Code), the Connectors menu (Claude Desktop), the MCP settings (Cursor). The server announces itself as `healthaccess-mcp`, title "Health Access MCP". `npx -y -p healthaccess-mcp healthaccess doctor` checks the folder: directories, index health, every JSON file, schema versions; exit code 1 on problems. Once the client has started the server, the Health Access app shows "Connected" with the client's name.

First thing to say after setup: "List my last 5 workouts, one line each. Then open the newest one and explain it in plain words. Ask me how it felt before you judge it."

## 6. The folder

```
<folder>/
  index.json                              one row per workout, newest first; rewritten by the app after every export
  briefing.md                             one page any AI can read
  workouts/
    2026-05-14_0712_PoolSwim_7A1C3E90.json   <local yyyy-MM-dd_HHmm>_<Activity>_<first 8 chars of the HealthKit UUID>
    2026-05-12_0630_IndoorRow_3F8B2D41.json
  vitals/
    2026-05-14.json                       one per day, rewritten when values change
  days/
    2026-05-14.json                       one per day, every Health group (v0.4; vitals/ stays for one release)
  catalog.json                            which Health types have data and where they were exported (v0.4)
  profile.json                            age, birth year, sex, blood type, move mode (v0.4)
  plans/
    2026-05-13T19:02:11Z-s12.json         written by the MCP (push_plan) or the CLI, or by the AI directly
    2026-05-13T19:02:11Z-s12.status.json  written by the app: did it reach the Watch
  mcp/clients/
    <id>.json                             presence file written by the MCP: client, machine, counts; never arguments or results
```

The same layout, filled with synthetic data, is the `examples/` folder of the repository; every excerpt in this file is taken from it.

Who writes what:
- The app writes `workouts/`, `vitals/` (`days/`, `catalog.json`, `profile.json` from v0.4), `index.json`, `plans/*.status.json`, and `briefing.md`.
- The MCP and CLI write `plans/<id>.json` and `mcp/clients/<id>.json` (section 8), and may update exactly two keys of a workout file, `effort` and `feel`, through `rate_workout`.
- Nothing else writes. Nothing deletes. Export never overwrites a workout file; a duplicate (same start within 2 s, same source) stays on disk and is left out of `index.json`.
- All JSON: UTF-8, sorted keys, ISO 8601 UTC timestamps with `Z`. Local time is in the file name and in `metadata.HKTimeZone`.

## 7. Workout file, schema `healthaccess.workout.v1`

An example file, `workouts/2026-05-14_0712_PoolSwim_7A1C3E90.json`, trimmed. It comes from the synthetic folder `examples/` in the repository (generated, not a real person): a 1,200 m swim from the plan S12. The full file has 24 steps, 24 laps and 431 heart-rate samples; here three steps, two laps and three samples stand in for them. Keys are sorted on disk.

```json
{
  "schema": "healthaccess.workout.v1",
  "healthaccess_version": "0.4.0",
  "id": "7A1C3E90-5B2D-4F61-9C8E-2A7D40B6E1F3",
  "activity": "pool_swim",
  "source": "Apple Watch",
  "start": "2026-05-14T05:12:04Z",
  "end": "2026-05-14T05:48:10Z",
  "duration_s": 2166,
  "distance_m": 1200,
  "active_kcal": 338.6,
  "avg_hr": 129,
  "max_hr": 162,
  "pool_length_m": 50,
  "plan_ref": {"plan_id": "2026-05-13T19:02:11Z-s12", "name": "S12"},
  "steps": [
    {"key": "0.0.0", "block": 0, "rep": 0, "step": 0, "kind": "warmup", "label": "FR easy, find your breathing",
     "start": "2026-05-14T05:12:04Z", "end": "2026-05-14T05:16:43Z", "duration_s": 279,
     "distance_m": 200, "avg_hr": 100, "pace_s_per_100m": 139.5, "goal_met": true},
    {"key": "1.0.0", "block": 1, "rep": 0, "step": 0, "kind": "work", "label": "DRILL 6-3-6: 6 kicks side, 3 strokes",
     "start": "2026-05-14T05:16:43Z", "end": "2026-05-14T05:18:08Z", "duration_s": 85,
     "distance_m": 50, "avg_hr": 125, "pace_s_per_100m": 170.0, "goal_met": true},
    {"key": "2.3.0", "block": 2, "rep": 3, "step": 0, "kind": "work", "label": "FR 100 steady, breathe every 3",
     "start": "2026-05-14T05:34:44Z", "end": "2026-05-14T05:36:56Z", "duration_s": 132,
     "distance_m": 100, "avg_hr": 151, "pace_s_per_100m": 132.0, "goal_met": true}
  ],
  "laps": [
    {"start": "2026-05-14T05:12:07Z", "end": "2026-05-14T05:13:14Z", "duration_s": 67, "stroke": "freestyle", "swolf": 88.0},
    {"start": "2026-05-14T05:13:14Z", "end": "2026-05-14T05:14:22Z", "duration_s": 68, "stroke": "freestyle", "swolf": 90.0}
  ],
  "hr_series": [["2026-05-14T05:12:05Z", 84], ["2026-05-14T05:12:10Z", 85], ["2026-05-14T05:48:06Z", 115]],
  "recovery_hr": {"end": 115, "1min": 104, "2min": 96},
  "effort": 6,
  "effort_source": "apple",
  "effort_estimated": 5,
  "feel": null,
  "metadata": {"HKAverageMETs": "6.84 kcal/hr·kg", "HKIndoorWorkout": "0", "HKLapLength": "50 m", "HKSwimmingLocationType": "1", "HKTimeZone": "Europe/Berlin"}
}
```

Fields:
- `activity`: `pool_swim` | `open_water_swim` | `indoor_row` | `run` | `walk` | `cycle` | `other:<HealthKit raw type>`.
- Zones: new files carry no `zones`. Zone seconds are computed by the MCP and the CLI from `hr_series` (each sample's time until the next sample, capped at 60 s, inside the workout) with the bounds from `zone_bounds` in config.toml or, without them, an estimate from the age in `profile.json` (max HR = 208 - 0.7 x age; bounds at 72 / 79 / 86 / 92 % of max). Every zone result states `bounds` and `bounds_source` (`config` or `estimated`). Files from before v0.4 may still carry app-computed `zones`; they are accepted.
- `steps`: one per interval of a structured workout. `key` is Apple's `block.rep.step`; `0.0.0` is the warm-up, a trailing single-step block the cool-down. `kind`: `warmup` | `work` | `recovery` | `cooldown`. `label` is the step name from the plan the AI wrote (Apple drops names on the way into HealthKit; the app joins them back from the matching plan). `pace_s_per_100m` only for steps of at least 20 m. `goal_met` can be null. A free workout has `steps: []`.
- `laps`: one per pool length; `stroke`: freestyle | backstroke | breaststroke | butterfly | mixed | kickboard; `swolf`.
- `hr_series`: `[timestamp, bpm]` about every 5 s. The MCP omits it unless `include_hr_series` is true.
- `recovery_hr`: heart rate at the end and 1 and 2 minutes after; null right after a background export, filled in on the next run.
- `effort` (1 to 10 or null) and `feel` (text or null): the athlete's rating. `effort_source` says where it came from: `apple` for the rating made on the Watch (the Watch asks after the workout; the app never asks), `ai` for `rate_workout`, `app` in files written by older builds. `effort_estimated` is Apple's own estimate, never used as `effort`. `rate_workout` writes `effort_source: "ai"` and must only be called with a number the athlete said.
- `plan_ref`: `{plan_id, name}` of the plan the session was started from (matched by the WorkoutKit id the app recorded, else by sport and scheduled time within 2 h), or null for a workout started by hand.
- `metadata`: Apple's raw workout metadata as strings.

## 8. Vitals, index, plan status

`vitals/<yyyy-MM-dd>.json`, schema `healthaccess.vitals.v1`, every field nullable (from the example folder):

```json
{"schema": "healthaccess.vitals.v1", "date": "2026-05-14", "resting_hr": 54, "hrv_sdnn_ms": 58.3, "sleep_s": 26160, "body_mass_kg": 78.4, "steps": 9412, "vo2max": 44.1, "bp": null}
```

From v0.4 the app writes `days/<yyyy-MM-dd>.json` (schema `healthaccess.day.v1`) with every Health group that has data: `activity` (rings, steps, distances, energy, exercise and stand minutes, daylight), `heart` (resting, walking average, min/avg/max, HRV, VO2max, events), `respiratory`, `sleep` (stages and sessions), `body`, `blood`, `mobility`, `hearing`, `nutrition`, `mind`, `symptoms`, `cycle`, `medications`, `hygiene`, `uv`, `wheelchair`. Inside a present group, absent values are explicit `null`; `vitals/` is kept for one release. Trimmed example (`examples/days/2026-05-14.json`):

```json
{
  "schema": "healthaccess.day.v1",
  "date": "2026-05-14",
  "activity": {
    "rings": {
      "exercise_min": {
        "actual": 47,
        "goal": 30
      },
      "move_kcal": {
        "actual": 712.3,
        "goal": 650
      },
      "move_mode": "active_energy",
      "stand_hours": {
        "actual": 13,
        "goal": 12
      }
    },
    "steps": 9412,
    "distance_walking_running_m": 7180.4,
    "distance_swimming_m": 1200,
    "active_energy_kcal": 712.3,
    "exercise_min": 47,
    "time_in_daylight_min": 63
  },
  "heart": {
    "resting_hr": 54,
    "hr": {
      "avg": 72,
      "max": 162,
      "min": 47,
      "samples": 1184
    },
    "hrv_sdnn_ms": 58.3,
    "vo2max": 44.1
  },
  "sleep": {
    "asleep_s": 26160,
    "deep_s": 4980,
    "rem_s": 5760
  }
}
```

`catalog.json` lists every HealthKit type the app knows with `has_data`, `samples_90d`, `first`, `last` and `exported_in` (`workouts`, `days`, `ecg`, `profile` or `none`), so `healthaccess doctor` can report a type with data that was exported nowhere. `profile.json` carries `age`, `birth_year`, `biological_sex`, `blood_type`, `wheelchair_use`, `activity_move_mode`, `fitzpatrick_skin_type`.

`sleep_s` is credited to the morning the sleep ended, from the one source with the most sleep. `hrv_sdnn_ms` is the day's average; `resting_hr`, `body_mass_kg`, `vo2max` and `bp` (`{sys, dia, at}`) are the day's latest; `steps` the day's sum. A day with no values gets no file.

`index.json`, schema `healthaccess.index.v1`: `{"schema", "updated", "workouts": [{"id", "file", "activity", "start", "duration_s", "distance_m", "avg_hr", "effort", "plan_name"}]}`, newest first, `file` relative to the folder (`workouts/<name>.json`). The MCP lists from it and opens files on demand; if the index lags behind the files, ids are also resolved by scanning `workouts/`.

`plans/<id>.status.json`, written by the app (from the example folder):

```json
{"plan_id": "2026-05-13T19:02:11Z-s12", "state": "scheduled", "at": "2026-05-13T19:04:40Z", "method": "schedule", "workoutkit_id": "D4E7A2C1-6F3B-4E8A-9B5C-1A2F3E4D5C6B", "scheduled_for": "2026-05-14T05:00:00Z", "error": null}
```

`state`: `scheduled` | `failed` | `cancelled` (no file yet = `pending`). `method`: `schedule` (WorkoutKit scheduled it for a date, verified) or `preview` (installed through Apple's "Add to Watch" sheet, which does not report back; the app asked the user). `workoutkit_id` links the finished workout back to the plan.

`mcp/clients/<id>.json`, written by the MCP server on start and after tool calls (at most once a minute), one file per machine and client: `{"schema": "healthaccess.client.v1", "id": "<stable id per machine+client>", "client": {"name": "Claude Code", "version": "..."}, "machine": "Alex's MacBook Pro", "mcp_version": "0.2.0", "first_seen": "...", "last_seen": "...", "last_tool": "list_workouts", "calls": 123}`. The app shows "Connected · <client> on <machine> · last seen <relative>" when any file is newer than 7 days, else "Not connected yet". Never tool arguments or results.

`briefing.md`: one page of Markdown the app rewrites after every sync. Sections in order: title with the athlete's name and the time written; Last 4 weeks (per ISO week: sessions, distance, time, mean effort); Recent sessions (newest first, max 10, one line each); Vitals (latest resting HR, HRV, sleep, weight with dates and 21-day direction); Next session; Open (unrated sessions, plans waiting for a tap); Limits (the two fixed sentences). No charts, no JSON, under 60 lines.

## 9. Tools

All results are JSON text. Domain errors (unknown id, failed validation) come back as tool errors with the reason. Ids: the full HealthKit UUID, the 8-character short id (the suffix of the file name) or the file name all work; resolved through `index.json` first, then by scanning `workouts/`.

- `list_workouts {since?, sport?, limit?=20}` (read-only). `since`: `YYYY-MM-DD` or RFC 3339. `sport`: `pool_swim`, `indoor_row`, `cycle`, `walk`, `run`, ... (`swim` matches both swim kinds). Returns `total_workouts`, `matched`, `returned`, and `rows`, newest first, each with `id`, `short_id`, `start`, `activity`, `duration_s`, `distance_m`, `avg_hr`, `effort`, `plan_name`, `file` and a one-line `summary` written for an LLM, like `2026-05-14 Pool swim "S12" · 1200 m · 36:06 · avg HR 129 (max 162) · Z1-2 93% · effort 6/10 (apple) · best FR 100 2:12 -> 284 beats/100 m` (the example swim).
- `get_workout {id, include_hr_series?=false, include_laps?=true}` (read-only). The full workout document plus `summary`, `file` and `cardiac_cost` (`beats_per_100m`, `best_100_pace_s`, `avg_hr`, `basis`).
- `get_vitals {days?=30}` (read-only). The vitals files of the last N days, oldest first, with `latest` and simple `averages`. Empty with a note until the app has written vitals.
- `training_summary {weeks?=8}` (read-only). One entry per ISO week ending in the current week, empty weeks included: `sessions`, `duration_s`, `distance_m`, duration-weighted `avg_hr`, `z12_pct` (share of time in zones 1 and 2), `mean_effort` over rated sessions, `rated_sessions`, `cardiac_cost` (mean over swims), `by_sport`. Plus `cardiac_cost_trend` (one point per swim) and `notes` stating the heuristics. Cardiac cost = avg HR x best freestyle 100 m pace (s) / 60 = heart beats per 100 m; lower is better; compare sessions of similar structure.
- `rate_workout {id, effort, feel?}` (writes). Stores `effort` (1 to 10) and, when given, `feel` in the workout file; only those two keys change (atomic rewrite). Updates the matching `index.json` row if the index lists the workout. Omitting `feel` keeps the previous note. The AI must ask the athlete for the number, never guess it.
- `push_plan {plan}` (writes). Validates a plan (section 10) and writes `plans/<id>.json` with `id = <RFC 3339 UTC seconds>-<slug(name)>`. Returns `id`, `file`, `path`, `planned_distance_m`, `planned_time_s`, the stored `plan` and a `next` hint. Every validation violation is reported in one message.
- `get_plan_status {id}` (read-only). `{plan_id, state, at, error}` plus `method`, `workoutkit_id`, `scheduled_for` when present. `state`: `pending` | `scheduled` | `failed` | `cancelled`.
- `list_plans {}` (read-only). Every plan in `plans/` with its state, planned distance and time, newest first.

Resources: `healthaccess://index` (the deduplicated index), `healthaccess://workout/<id>` (one workout, heart-rate series included; template `healthaccess://workout/{id}`).

Prompts: the server exposes the six ideas of section 11 as MCP prompts under the ids given there. They are suggestions, not a step of the setup; the text works pasted as well.

CLI equivalents: `healthaccess list [--since] [--sport] [--limit]`, `healthaccess show <id> [--hr]`, `healthaccess summary [--weeks 8]`, `healthaccess rate <id> <effort> [feel words]`, `healthaccess plan push <plan.json>`, `healthaccess plan status <id>`, `healthaccess plan list`, `healthaccess doctor`. `--dir` and `--json` work on every subcommand.

## 10. Plan format, schema `healthaccess.plan.v1`

What the AI passes to `push_plan` (the server fills `schema`, `id`, `created_at`, `created_by`):

```json
{
  "name": "S27",
  "sport": "pool_swim",
  "pool_length_m": 50,
  "warmup": {"goal": {"type": "time_s", "value": 120}, "zone": 1},
  "blocks": [
    {"repeat": 4, "steps": [
      {"kind": "work", "goal": {"type": "distance_m", "value": 50}, "zone": 1, "label": "FR easy, long strokes"},
      {"kind": "recovery", "goal": {"type": "time_s", "value": 30}}
    ]}
  ],
  "cooldown": {"goal": {"type": "distance_m", "value": 100}, "zone": 1},
  "notes": "what this session is for, shown in the app",
  "scheduled_for": "2026-10-27T07:30:00Z"
}
```

Rules the server checks:
- `sport` is `pool_swim` or `indoor_row` (nothing else yet).
- `name` not empty, at most 40 characters. Use the next free S-number (S13 after S12 in the example folder).
- At least one block; `repeat` 1 to 99; each block at least one step.
- `goal.type` is `time_s` or `distance_m`, with a positive value.
- `zone`, when given, 1 to 5 (the Watch's own heart-rate zones).
- `label` at most 40 characters, written as an instruction readable on the wrist: "KICK on back, no board, hips up".
- `kind` is `work` or `recovery`. Rests are real rests.
- `warmup` and `cooldown` are optional single steps. A 2 minute time warm-up first lets the athlete start the workout in the shower so the Watch is in swim mode at the pool.
- `pool_length_m` is a reminder for the athlete only; the Watch keeps its own pool length setting.
- `scheduled_for` (optional, RFC 3339 UTC) is used to match the finished workout to the plan when the exact WorkoutKit id is missing.

The full plan behind the example swim, `plans/2026-05-13T19:02:11Z-s12.json` in `examples/` (1,200 m in six parts, about 36 minutes), as `push_plan` wrote it:

```json
{
  "schema": "healthaccess.plan.v1",
  "id": "2026-05-13T19:02:11Z-s12",
  "name": "S12",
  "sport": "pool_swim",
  "pool_length_m": 50,
  "warmup": {"goal": {"type": "distance_m", "value": 200}, "zone": 1, "label": "FR easy, find your breathing"},
  "blocks": [
    {"repeat": 3, "steps": [
      {"kind": "work", "goal": {"type": "distance_m", "value": 50}, "zone": 1, "label": "DRILL 6-3-6: 6 kicks side, 3 strokes"},
      {"kind": "work", "goal": {"type": "distance_m", "value": 50}, "zone": 1, "label": "FR easy, long strokes"},
      {"kind": "recovery", "goal": {"type": "time_s", "value": 30}}
    ]},
    {"repeat": 4, "steps": [
      {"kind": "work", "goal": {"type": "distance_m", "value": 100}, "zone": 2, "label": "FR 100 steady, breathe every 3"},
      {"kind": "recovery", "goal": {"type": "time_s", "value": 40}}
    ]},
    {"repeat": 2, "steps": [
      {"kind": "work", "goal": {"type": "time_s", "value": 120}, "zone": 1, "label": "KICK on back, no board, hips up"},
      {"kind": "recovery", "goal": {"type": "time_s", "value": 45}}
    ]},
    {"repeat": 1, "steps": [
      {"kind": "work", "goal": {"type": "distance_m", "value": 100}, "zone": 2, "label": "FR 100, carry the drill into it"}
    ]}
  ],
  "cooldown": {"goal": {"type": "distance_m", "value": 100}, "zone": 1, "label": "Easy, any stroke, long exhale"},
  "notes": "Technique week 2. Short drill reps, then four steady 100s to carry the feel over. Kick on back is for the hips, not for speed. Target effort 5 to 6.",
  "created_by": "claude-code",
  "created_at": "2026-05-13T19:02:11Z",
  "scheduled_for": "2026-05-14T05:00:00Z"
}
```

The flow after `push_plan`: the folder syncs to the phone; the app lists the plan as "Your AI wrote S27" within about a minute (and sends that one notification if it was not in front); the user taps "Put on Watch" (WorkoutKit schedules it for a date, by default the next day at 10:00, or Apple's "Add to Watch" sheet installs it as a plain custom workout); the app writes the status file; `get_plan_status` reports it. After the session, the exported workout carries `plan_ref` and the step labels. Tell the user: "It is in the app under Your AI wrote S27. Tap Put on Watch."

## 11. Ideas for your AI: six prompts, suggestions only

These are ideas, not a step of the setup: use them, change them or ignore them. What you share with an AI, and what it tells you, is between you and that AI. Every prompt asks before it reads data, and reads data before it writes anything. A plan written without asking how you feel is a guess with formatting. Voice: plain, short, no consultant words. The AI talks to the athlete the way a good coach does.

### 1. Build my next swim session
id: `next_swim_session` · args: none

Ask me these, one message, numbered, then wait:
1. Pool length today (25 m or 50 m)?
2. How much time do you have, door to door?
3. How did the last session feel, 1 to 10, and anything sore?
4. What is this month for: getting back into it, building distance, getting faster, or just enjoying it?
5. Anything I should avoid (strokes, drills, equipment you don't have)?

Then read `training_summary` for the last 4 weeks and `get_workout` for the last 3 swims. Note what the effort ratings say versus what the heart rate says, those often disagree and effort wins.

Write one session that fits the answers: a 2 minute warm-up step first (the athlete starts it in the shower so the Watch is in swim mode at the pool), then a short easy warm-up swim, then the main part, then a cool-down. Every step label is an instruction the athlete can read on the wrist, under 40 characters, like "FR easy, long strokes" or "KICK on back, no board, hips up". Rests are real rests. Name it with the next free S-number.

Show it to me as a list with a one-line why. If I say yes, call `push_plan`, then tell me: "It is in the app under Your AI wrote S27. Tap Put on Watch."

### 2. Build my next rowing session
id: `next_rowing_session` · args: none

Ask first, one message, numbered:
1. Which machine, and which resistance level do you normally use?
2. How much time?
3. Has heart rate from the Watch been believable on the rower, or does it read low? (It often does.)
4. How did the last row feel, 1 to 10?
5. Legs, back or lungs: which one usually gives out first?

Then read the last 3 rowing sessions and `training_summary`. If the Watch heart rate is unreliable, govern the session by stroke rate and effort, not by heart-rate zones, and say so in the step labels ("20 spm, pull harder if HR under 134").

Write the session with a 3 minute warm-up, pieces of 2 to 6 minutes with real breaks, and labels that say exactly what to do, under 40 characters. Show it, wait for yes, then `push_plan`.

### 3. Weekly check-in
id: `weekly_checkin` · args: none

Ask, one message:
1. How was the week, in two sentences?
2. Sleep: roughly how many hours, and how did you wake up?
3. Stress at work or home, 1 to 10?
4. How many sessions can you realistically fit next week, and which days?
5. Anything hurting?

Then read `training_summary` for 4 weeks and `get_vitals` for 14 days. Compare the plan to what actually happened: sessions done versus planned, effort versus heart rate, resting heart rate and HRV trend.

Reply with: what went well (one specific thing with a number), what to change (one thing), and next week as a list of sessions with a sentence each. Do not write plan files until I say yes to the list.

### 4. Explain my last session
id: `explain_last_session` · args: `id` (optional)

One question: what did you want from this session?

Then `get_workout` on the latest session (or the id I gave) with laps. Explain it in plain words: what the parts were, where the heart rate went relative to the plan, where pace changed, anything odd (a step that was swum fast when it said easy, a length the Watch miscounted). End with one sentence about what it means for next time. No charts, no jargon without a one-line explanation.

### 5. Am I overdoing it?
id: `overdoing_it` · args: none

Ask:
1. How have you been sleeping the last week?
2. Motivation to train, 1 to 10?
3. Any illness, travel, or big life stress right now?

Then `get_vitals` for 21 days (resting heart rate, HRV, sleep) and `training_summary` for 4 weeks (load, effort). Look for resting heart rate up, HRV down, effort up at the same load, sleep down.

Answer as a hypothesis, not a verdict: what the numbers suggest, how confident you are, and what would change your mind. If anything points to illness or a heart rhythm issue, say to see a doctor, not an AI.

### 6. Prepare this for my coach
id: `coach_summary` · args: `weeks` (default 4)

Ask: what does your coach care about most, and how do they like to receive things (email, PDF, chat)?

Then read `training_summary` and the sessions for that period. Write a one-page summary a coach can use: sessions done, total volume, how hard they felt versus heart rate, best efforts, what the athlete reported, open questions. Plain language, numbers where they help, nothing invented. Offer it as text first, then in the format they asked for.

## 12. Limits

- Health data can only be read while the phone is unlocked (Apple). A workout finished with the phone in a bag exports the next time the phone is unlocked, not before. The app says so instead of pretending.
- The Watch keeps its own pool length setting; a plan cannot set it (WorkoutKit has no parameter for it).
- Step names on the Watch need iOS 18; on iOS 17 the workout installs without labels. Labels longer than 40 characters are cut.
- Plans: pool swim and indoor rowing only, today.
- `recovery_hr` is null right after a background export and filled in on the next run.
- Rowing distance per step needs iOS 18; on iOS 17 only the workout total is known.
- Apple's "Add to Watch" sheet does not report back; a plan installed that way is marked `scheduled` with `method: preview` after the user confirms.
- Times are UTC everywhere in the files and tool results; the local time is in the file name and in `metadata.HKTimeZone`.
- Effort and heart rate often disagree; effort wins. The AI never rates a session on the athlete's behalf.
- Health questions that point to illness or a heart rhythm issue belong with a doctor, not an AI.

## 13. Aliases from the "Tide" era, accepted forever

- Schema ids: `tide.workout.v1` and `tide.workout.v0` (for `healthaccess.workout.v1`), `tide.vitals.v1`, `tide.index.v1`, `tide.plan.v1`. The workout key `tide_version` for `healthaccess_version`.
- Environment: `TIDE_DIR` for `HEALTHACCESS_DIR`; `TIDE_CONFIG`, `TIDE_LOG` for `HEALTHACCESS_CONFIG`, `HEALTHACCESS_LOG`.
- Config file: `~/.config/tide/config.toml` is read when `~/.config/healthaccess/config.toml` is absent.
- Resources: `tide://index`, `tide://workout/<id>`.
- Not aliased: the binaries (`healthaccess-mcp`, `healthaccess`; the old `tide-mcp` and `tide` are gone, re-register the server) and the crate names.

## 14. Telemetry

Off by default on both sides. The app sends nothing unless the user turns on usage statistics; then exactly `app_opened`, `export_completed {workout_count, duration_ms, trigger}`, `export_failed {error_domain, code}`, `plan_scheduled`, `plan_put_on_watch {method}`, `setup_message_copied`, plus app and OS version and a random install id. The server sends nothing unless `telemetry = true` and a PostHog key are set in config.toml (or `--telemetry` is passed); then exactly `mcp_started {version}` and `mcp_tool_called {tool, duration_ms, ok, error_kind?}`. Never tool arguments, results, health values, file names or paths.

## 15. Where to read more

- Tool reference with return shapes and heuristics: https://healthaccessmcp.com/ref/mcp.md
- Data contract, every field: https://healthaccessmcp.com/ref/schema.md
- Ideas for your AI (the six prompts), source file: https://healthaccessmcp.com/ref/prompts.md
- Synthetic example folder: https://healthaccessmcp.com/examples/README.md
- Site: https://healthaccessmcp.com/ (pages: /docs/claude-code, /docs/claude-desktop, /docs/cursor, /docs/chatgpt, /docs/local-models, /docs/files, /docs/plans, /docs/prompts, /docs/privacy, /docs/compare)
- License: MIT for the server and CLI. Apple, Apple Watch, Apple Health and HealthKit are trademarks of Apple Inc.; the project is not affiliated with Apple.