MCP Server
Tools
All available MCP tools for the GymUp coaching platform.
All tools require an active GymUp subscription.
| Tool | Description |
|---|
search_exercises | Search the exercise library by name, muscle group, type, difficulty, or equipment. Typo-tolerant name search, paginated (limit 1-50, default 20, plus offset/hasMore); unilateral , left/, right mirror rows are hidden. Pass detailed: true (ideally with limit: 1) for parsed muscles on a single exercise. |
resolve_exercise_names | Batch-resolve user-supplied exercise names to catalog IDs — deterministic trigram matching, up to 3 candidates per name with a similarity score, or no_match. Step 1 of the program-import recipe (translate names to English → resolve all in ONE call, ≤30 names → confirm substitutions → prepare_user_program); the full recipe ships in the tool description. |
| Tool | Description |
|---|
get_athlete_profile | Retrieve athlete profile: name, age, height, weight (+ display unit kg/lbs), gender, training days, volume level, notes, saved hard constraints, onboarding status, and a missing list of required fields. |
save_athlete_profile | Save or update athlete profile: name, weight, measurements, training days, notes, and the volume level (1-5, drives exercises per day / session duration). Every weight/measurement write also lands as a dated body-metrics history entry. Pass metrics_date to log historical weight without regressing the latest-state cache. |
get_body_metrics | Body-metrics history (body weight, tape measurements), one entry per day, newest first — the source of truth for weight-evolution questions. Each row: ISO date, metrics (kg / cm), optional note. Filters: half-open [from, to). Default limit 90 rows, max 365. |
| Tool | Description |
|---|
generate_smart_program | Generate a fully personalized training program (the next "Chapter") using the athlete's profile, history, periodization state, memories, hard constraints, and evidence-based coaching rules — and save it as a draft. Returns the draft program_id (two IDs for a coordinated A/B pair) plus an arc_update payload for activation. Server-side generation — coaching guidelines never leave the server. Activation happens via the in-app preview button, or commit_program_draft on an explicit ask. |
| Tool | Description |
|---|
get_programs | The athlete's programs. detail: "summary" (default): up to 5 recent summaries (name, phase, dates, days_per_week, per-day exercise counts — metadata only). detail: "rows": flat per-exercise rows (inferred phase_type; prescribed reps, per-set RPE/tempo, rest, superset/biset structure, duration/time_based — read rpe_per_set first, a nonzero flat rpe applies when it is empty; durations and rest are seconds). Filters: program_id, phase_type, date overlap, muscle (rows only). Soft-deleted hidden; drafts hidden from listings unless program_id targets one. Merges the former get_program_history + get_program_exercises_raw. |
get_periodization_context | Current training phase state: last program end date, phase type, weeks since last deload, recent phase sequence, plus whether the athlete is currently in a program (and which one). |
get_activity_logs_raw | Raw completed-activity rows newest-first; each row inlines e1rm and volume_load, plus per-set rpe_per_set/tempo_per_set and biset_label/rest_after_exercise when set (durations and rest are seconds). Filters: exercise_id, half-open [from, to), exercise_type, muscle, done. Pagination via cursor (ISO date). Default limit 200, max 1000. Use for any analytical question over logged history — aggregate the rows yourself. |
| Tool | Description |
|---|
prepare_user_program | Stage a USER-supplied program (pasted text / photo / PDF import, manually described workout) as draft(s). Source values are kept verbatim; omitted reps/rest get coach defaults, reported in filled_prescriptions (RPE/tempo are never invented). Two alternating weeks = two programs in ONE call (server links the A/B pair). Not for AI-generated programs — those come from generate_smart_program. |
commit_program_draft | Activate draft program(s) by program_ids (from generate_smart_program or prepare_user_program), threading back the generator's arc_update payload verbatim when there is one. A/B pairs are saved atomically with rotation_pair_id linkage. Normally the athlete activates from the in-app preview — call this only on an explicit "activate it now". |
update_program | Replace all exercises in an existing program (manual surface — prescriptions required, saved verbatim). Also accepts new start/end dates and rotation fields. Refuses to rewrite an A/B rotation leader (AB_PAIR_LEADER_REWRITE) — use the day-level tools for pairs. |
edit_program_day | Surgical ops on a single day (add/remove an exercise, group into biset/superset) without resending the whole day. Propagates to the A/B twin week by default (opt out with this_week_only). |
patch_program_exercise | Atomically update ONE existing exercise (sets/reps/RPE/tempo, or a same-muscle swap via replace_with_exercise_id). On a swap the new exercise inherits the replaced slot's prescriptions unless you provide new ones. Rejected swaps return ranked suggestions; a replacement already on the day is refused (user-named) or substituted and reported (substituted_replacement). Propagates to the A/B twin week by default. For a single-date change, use patch_session_exercise. |
patch_session_exercise | Override ONE exercise for ONE session date: a same-muscle swap and/or a per-date prescription tweak. The weekly program is never touched; the override is applied at read time (get_day_session and the app's day screen). Swaps inherit the slot's prescriptions unless you provide new ones; omitted fields keep inheriting the program, so later program edits flow through. Past dates are refused, and the date must be a training day the program is active on (for A/B rotations, pass the week's own program_id; overrides never propagate to the twin week). Undo with revert_session_patch. |
revert_session_patch | Remove a session override for one exercise and date; the session falls back to the weekly program. Accepts the original or the replacement exercise id. |
reschedule_program | Change a program's start/end dates without touching its exercises. Accepts a symbolic target (latest_draft or active_today) so you rarely need a program_id; A/B pairs shift together. The result reports the program's status (a draft stays off the calendar) and any conflicts with other active programs. |
delete_program | Soft-delete a program — reversible via restore_program; cascades to the A/B rotation twin. Activity logs persist since they link to exercise_id+date, not program_id. |
restore_program | Restore a soft-deleted program (restoring an A/B leader restores its twin too). |
| Tool | Description |
|---|
get_day_session | Program day exercises with the full prescription (reps, per-set RPE/tempo, rest, biset label, note), estimated weights from history, the athlete’s logged_note for the date, and done flags. response_format: "concise" (default) omits media/tutorials/tips/equipment. |
log_activity | Save a workout log for a given exercise and date. activity_type: "strength" → up to 8 sets of {reps, weight, rpe?, rest?} (plus tempo/biset/rest_after); activity_type: "cardio" → duration_minutes. Auto-marks done = true (override with done: false). Merges the former log_strength_activity + log_cardio_activity. |
set_exercise_done | Toggle the done flag without touching weights (creates a minimal empty log when none exists). Use to uncheck a session. |
delete_activity_log | Hard-delete an activity log for one exercise + date (different from setting done: false). |
For reading workout history, use get_activity_logs_raw in the analytics section above (aggregate the rows for any custom query).
| Tool | Description |
|---|
search_memories | List recent memories (no query) or semantic-search them (with query). |
save_constraint | Persist a HARD training constraint — equipment whitelist, permanent exercise avoids, permanent muscle exclusions, or pinned favorites — enforced mechanically on every future generation and edit. |
save_memory | Save a long-term athlete fact (soft preference, injury context). |
delete_memory | Hard-delete a memory by ID (to edit, delete then re-save). |
Every tool declares MCP standard annotations (spec 2025-06-18) so your client can prompt for confirmation, throttle, or filter:
readOnlyHint — true for all search_*, get_*, resolve_exercise_names.destructiveHint — true for update_program, delete_program, delete_activity_log, delete_memory, revert_session_patch. Hosts that gate destructive calls (e.g. Claude Desktop's "Allow once / Always allow" prompt) will surface a confirmation for these.openWorldHint — true only for generate_smart_program (LLM call). Everything else operates on the athlete's own data.idempotentHint — true for reads, replaces, deletes, restores, upserts (save_athlete_profile, save_constraint, patch_session_exercise), log_activity, in-place edits (patch_program_exercise, reschedule_program), and set_exercise_done. false for commit_program_draft, prepare_user_program, save_memory (each call creates a distinct row), and edit_program_day (repeating an add appends again).