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. |
propose_replacements | Get the three replacement options to offer for ONE exercise the athlete wants swapped. The server reads the whole muscle group, drops anything already in that session, and an evaluation model ranks the candidates against the athlete's own words; date for a single session or day_index for the weekly template, equipment_for_this_session to honour an equipment limit, declined_exercise_ids for the next three. The ids it returns are the only ones an agent-picked swap may then apply. |
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, a per-date prescription tweak, or remove: true to take the exercise out of that one session while the weekly program keeps it. 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). An exercise that add_session_exercise put on that date cannot be swapped (SWAP_ON_ADDED_EXERCISE): undo the add, then add the one you want. Undo with revert_session_patch. |
add_session_exercise | Add ONE exercise to the session of ONE date. The weekly program, every other date and the A/B twin stay as they are. The coach layout places the exercise by movement (after_exercise_id overrides it) and the coach policy prescribes whatever you omit. An exercise already in the session, or a same-named twin of one, is refused; an exercise foreign to the day's muscle theme is refused unless user_requested_exercise: true. One side of a , left/, right pair brings the other. Adding back what that date removed undoes the removal. Undo with revert_session_patch. |
revert_session_patch | Undo one session override for one exercise and date: an overridden slot returns to the weekly prescription, a removed exercise comes back, an added one goes out (its logs are kept). Accepts the original or the replacement exercise id. |
move_session | Do ONE planned session on another date, skip it (omit to_date), or copy it (copy: true, the source keeps its logs). The weekly program is never touched and every other week stays as planned. Past target dates are refused, and a date that already has a session offers a stack, a shift, or a swap. Returns a batch_id undone by revert_session_move. |
swap_sessions | Exchange the sessions of TWO dates in one call: each date ends with the other's session. Both dates must carry exactly one session of the program (a date with no session that day is a plain move_session). Per-date exercise overrides follow their session. Returns a batch_id undone by revert_session_move. |
revert_session_move | Undo one move_session, swap_sessions or swap_rotation_weeks this_week call by its batch_id: the sessions return to their planned dates. Refused while a later change touched the same dates, which are listed so you can undo those first. |
swap_rotation_weeks | Invert the A and B weeks of an alternating pair: this_week trades them for one week only (undone by revert_session_move), permanent inverts the rotation for the rest of the program (undone by calling it again). |
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 and propose_replacements (both call a model). 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).