# TrueCoach MCP tools

> Every TrueCoach MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/truecoach

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

15 tools for TrueCoach on the Cotlet MCP server. Your agent picks them from tools/list.

- MCP server: `https://cotlet.dev/mcp/v1`
- Connects with: Your own TrueCoach coach account (on a Team Account, the coach whose clients and programs you want to use)
- Integration page: https://cotlet.dev/integrations/truecoach-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `truecoach_list_clients` | read | Your clients with client type, groups, 7, 30 and 90 day compliance rates and due date. |
| `truecoach_get_client` | read | One client: profile, client type, groups, compliance rates, due date and assigned programs. |
| `truecoach_get_dashboard` | read | Your overall compliance rate, clients under Needs Attention and clients due soon. |
| `truecoach_list_workouts` | read | Workouts on a client's workout calendar in a date range, with status. |
| `truecoach_get_workout` | read | Full workout: title, warmup, exercises and circuits, cooldown, and the results the client logged. |
| `truecoach_list_programs` | read | Programs in your account with tags and the clients they are assigned to. |
| `truecoach_list_metrics` | read | A client's metrics (for example back squat or body fat %) with their values over time. |
| `truecoach_list_messages` | read | Recent messages in your conversation with a client, newest first. |
| `truecoach_create_client` | write | Add a client. Remote and Dual clients get the TrueCoach invitation email right away. |
| `truecoach_create_workout` | write | Write a workout on a client's workout calendar for a given day. |
| `truecoach_assign_program` | write | Put a program on the workout calendars of clients or client groups. |
| `truecoach_unassign_program` | write | Remove a program from a client's calendar. Completed and missed workouts stay. |
| `truecoach_add_client_to_group` | write | Add a client to one of your client groups. A client can be in several groups. |
| `truecoach_update_metric` | write | Record a new value for one of a client's metrics. |
| `truecoach_send_message` | write | Message a client or every client in a group, as you. |

## List clients

MCP tool: `truecoach_list_clients`

Access: read.

Returns one item per client, active clients by default. Compliance is completed against assigned exercises, as TrueCoach shows it. Due date is the date of the furthest programmed workout. Results come in pages; use the cursor for the next one.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `group` | string | no | Only clients in this client group. |
| `client_type` | enum | no | remote, dual or in_person. Default: all. |
| `archived` | boolean | no | List archived clients instead of active ones. Default: false. |
| `limit` | integer | no | Page size. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_list_clients",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "clients": [
      {
        "client_id": "4821907",
        "name": "Sam Rivera",
        "client_type": "remote",
        "groups": [
          "Bootcamp"
        ],
        "compliance_7d": 50,
        "compliance_30d": 82,
        "compliance_90d": 88,
        "due_date": "2026-10-18"
      },
      {
        "client_id": "4821955",
        "name": "Alex Kim",
        "client_type": "dual",
        "groups": [
          "Bootcamp",
          "January"
        ],
        "compliance_7d": 100,
        "compliance_30d": 95,
        "compliance_90d": 91,
        "due_date": "2026-11-02"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Get client

MCP tool: `truecoach_get_client`

Access: read.

Returns the profile fields TrueCoach holds for the client, the three compliance rates and the programs assigned to them. In-Person clients have no client account, so they have no login. Archived clients can be read too.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from list_clients. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_get_client",
    "arguments": {
      "client_id": "client_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "client_id": "4821907",
    "name": "Sam Rivera",
    "email": "sam.rivera@example.com",
    "client_type": "remote",
    "groups": [
      "Bootcamp"
    ],
    "compliance_7d": 50,
    "compliance_30d": 82,
    "compliance_90d": 88,
    "due_date": "2026-10-18",
    "programs": [
      {
        "program_id": "30517",
        "name": "12 Week Hypertrophy"
      }
    ]
  },
  "isError": false
}
```

## Get dashboard

MCP tool: `truecoach_get_dashboard`

Access: read.

Returns what the TrueCoach dashboard shows. Needs Attention lists clients whose compliance rate dropped suddenly in a period. Due soon uses the threshold set in your TrueCoach settings.

### Parameters

No parameters.

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_get_dashboard",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "overall_compliance": 84,
    "needs_attention": [
      {
        "client_id": "4821907",
        "name": "Sam Rivera",
        "period": "7d",
        "compliance": 50
      }
    ],
    "due_soon": [
      {
        "client_id": "4821907",
        "name": "Sam Rivera",
        "due_date": "2026-10-18"
      }
    ]
  },
  "isError": false
}
```

## List workouts

MCP tool: `truecoach_list_workouts`

Access: read.

Returns workouts oldest first with date, title and status. A day can hold more than one workout. Use get_workout for the exercises and logged results.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from list_clients. |
| `from` | date | yes | First day of the range. |
| `to` | date | yes | Last day of the range. |
| `status` | enum | no | all, completed, missed or upcoming. Default: all. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_list_workouts",
    "arguments": {
      "client_id": "client_8c41d2",
      "from": "2026-10-01",
      "to": "2026-10-01"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "workouts": [
      {
        "workout_id": "91374520",
        "date": "2026-10-08",
        "title": "Upper body A",
        "status": "completed"
      },
      {
        "workout_id": "91374611",
        "date": "2026-10-10",
        "title": "Lower body B",
        "status": "missed"
      }
    ]
  },
  "isError": false
}
```

## Get workout

MCP tool: `truecoach_get_workout`

Access: read.

Returns the parts in the order the client sees them. Results are what the client entered; for In-Person clients, the coach entered them. A missed workout has no results.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `workout_id` | string | yes | Workout ID from list_workouts. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_get_workout",
    "arguments": {
      "workout_id": "workout_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "workout_id": "91374520",
    "client_id": "4821907",
    "date": "2026-10-08",
    "title": "Upper body A",
    "status": "completed",
    "warmup": "5 min row, band pull-aparts",
    "items": [
      {
        "type": "exercise",
        "name": "Bench Press",
        "description": "4 sets of 6, rest 2 min",
        "results": "4x6 at 80 kg"
      },
      {
        "type": "exercise",
        "name": "Pull-up",
        "description": "3 sets to near failure",
        "results": "8, 7, 6"
      }
    ],
    "cooldown": "5 min easy walk"
  },
  "isError": false
}
```

## List programs

MCP tool: `truecoach_list_programs`

Access: read.

Returns your programs, filtered by program tag if you give one. On Team Accounts, private programs are visible only to coaches with admin privileges.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `tag` | string | no | Only programs with this program tag. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_list_programs",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "programs": [
      {
        "program_id": "30517",
        "name": "12 Week Hypertrophy",
        "tags": [
          "strength"
        ],
        "weeks": 12,
        "assigned_clients": 6
      },
      {
        "program_id": "30644",
        "name": "Bootcamp Base",
        "tags": [
          "group"
        ],
        "weeks": 4,
        "assigned_clients": 11
      }
    ]
  },
  "isError": false
}
```

## List metrics

MCP tool: `truecoach_list_metrics`

Access: read.

Returns the metrics assigned to the client, grouped as in the Metric Manager, with each recorded value and date, newest first. Metrics linked to a workout exercise update when the client logs a result.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from list_clients. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_list_metrics",
    "arguments": {
      "client_id": "client_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "client_id": "4821907",
    "metrics": [
      {
        "name": "Back Squat",
        "unit": "kg",
        "values": [
          {
            "date": "2026-10-08",
            "value": "110"
          },
          {
            "date": "2026-09-10",
            "value": "105"
          }
        ]
      }
    ]
  },
  "isError": false
}
```

## List messages

MCP tool: `truecoach_list_messages`

Access: read.

Returns text messages with sender and time. Reading does not mark anything as sent or change the conversation.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from list_clients. |
| `limit` | integer | no | Number of messages. Default: 30. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_list_messages",
    "arguments": {
      "client_id": "client_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "client_id": "4821907",
    "messages": [
      {
        "sender": "client",
        "sent_at": "2026-10-10T18:42:00+02:00",
        "body": "Sorry, travelling this week."
      },
      {
        "sender": "coach",
        "sent_at": "2026-10-08T09:10:00+02:00",
        "body": "Great session yesterday."
      }
    ]
  },
  "isError": false
}
```

## Create client

MCP tool: `truecoach_create_client`

Access: write. Confirm: waits for the user's OK before it runs.

Creates the client in your list. First and last name are required; email is required for remote and dual clients. In-Person clients get no invitation and no account. A client who already has a TrueCoach account under another coach cannot be added with the same email. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `first_name` | string | yes | First name. |
| `last_name` | string | yes | Last name. |
| `email` | string | no | Required for remote and dual clients. |
| `client_type` | enum | no | remote, dual or in_person. Default: remote. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_create_client",
    "arguments": {
      "first_name": "Maya",
      "last_name": "Okafor",
      "email": "maya.okafor@example.com",
      "client_type": "remote"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "client_id": "4822040",
    "name": "Maya Okafor",
    "client_type": "remote",
    "invitation_sent": true
  },
  "isError": false
}
```

## Create workout

MCP tool: `truecoach_create_workout`

Access: write.

Adds the workout to the calendar and returns its ID. Warmup and cooldown are free text. Sets, reps, tempo and rest go in each exercise description. Exercise names come from the TrueCoach library. It does not ask for your OK: the client sees the workout on their calendar, but you can edit or delete it in TrueCoach.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from list_clients. |
| `date` | date | yes | Day on the workout calendar. |
| `title` | string | no | Workout title the client sees. |
| `warmup` | string | no | Warmup text, shown as written. |
| `items` | object | yes | Ordered list of exercises (name, description, optional superset link) and circuits (description). |
| `cooldown` | string | no | Cooldown text, shown as written. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_create_workout",
    "arguments": {
      "client_id": "4821907",
      "date": "2026-10-15",
      "title": "Lower body A",
      "warmup": "5 min bike, 2 rounds: 10 glute bridges, 10 goblet squats",
      "items": [
        {
          "type": "exercise",
          "name": "Back Squat",
          "description": "5 sets of 5, tempo 3010, rest 2 min"
        },
        {
          "type": "exercise",
          "name": "Romanian Deadlift",
          "description": "3 sets of 8, rest 90 s"
        },
        {
          "type": "circuit",
          "description": "10 min EMOM: 12 KB swings, 8 push-ups"
        }
      ],
      "cooldown": "5 min easy walk, hip flexor stretch"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "workout_id": "91374700",
    "client_id": "4821907",
    "date": "2026-10-15",
    "title": "Lower body A",
    "status": "upcoming",
    "items": 3,
    "due_date": "2026-10-18"
  },
  "isError": false
}
```

## Assign program

MCP tool: `truecoach_assign_program`

Access: write.

Assigns from the start date on the program day you choose. Completed and missed workouts are never touched. Later edits to the program reach clients only if Sync is on for that program in TrueCoach. It does not ask for your OK, because unassign_program undoes it.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `program_id` | string | yes | Program ID from list_programs. |
| `client_ids` | string[] | no | Clients to assign. Give this or group_names. |
| `group_names` | string[] | no | Client groups to assign. |
| `start_date` | date | yes | Calendar date of the first workout. |
| `start_day` | integer | no | Program day to start on. Default: 1. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_assign_program",
    "arguments": {
      "program_id": "30517",
      "group_names": [
        "Bootcamp"
      ],
      "start_date": "2026-10-19",
      "start_day": 1
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "program_id": "30517",
    "assigned_clients": 6,
    "start_date": "2026-10-19",
    "start_day": 1
  },
  "isError": false
}
```

## Unassign program

MCP tool: `truecoach_unassign_program`

Access: write.

Removes the upcoming workouts of the program from the client calendar. It reaches no one and a new assign_program restores it, so it does not ask for your OK.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `program_id` | string | yes | Program ID from list_programs. |
| `client_id` | string | yes | Client ID from list_clients. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_unassign_program",
    "arguments": {
      "program_id": "program_8c41d2",
      "client_id": "client_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "program_id": "30517",
    "client_id": "4821907",
    "unassigned": true
  },
  "isError": false
}
```

## Add client to group

MCP tool: `truecoach_add_client_to_group`

Access: write.

Adds the group to the client and keeps their other groups. The group must exist in Manage Groups. It reaches no one, and removing the client from the group in TrueCoach undoes it, so it does not ask for your OK.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from list_clients. |
| `group_name` | string | yes | Client group name. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_add_client_to_group",
    "arguments": {
      "client_id": "client_8c41d2",
      "group_name": "group name"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "client_id": "4822040",
    "groups": [
      "January"
    ]
  },
  "isError": false
}
```

## Update metric

MCP tool: `truecoach_update_metric`

Access: write.

Updates the metric as a coach would in the Metric Manager on the client calendar. The metric must already be assigned to the client. It does not ask for your OK; clients can see their own metrics.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from list_clients. |
| `metric` | string | yes | Metric name from list_metrics. |
| `value` | string | yes | New value, in the metric's unit. |
| `date` | date | no | Date of the measurement. Default: today. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_update_metric",
    "arguments": {
      "client_id": "client_8c41d2",
      "metric": "metric",
      "value": "value"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "client_id": "4821907",
    "metric": "Back Squat",
    "value": "112.5",
    "date": "2026-10-11"
  },
  "isError": false
}
```

## Send message

MCP tool: `truecoach_send_message`

Access: write. Confirm: waits for the user's OK before it runs.

A message to a group reaches each client individually, as in TrueCoach. Clients who are not logged in to TrueCoach get the message text by email. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | no | One client. Give this or group_name. |
| `group_name` | string | no | Each client in the group gets the message individually. |
| `body` | string | yes | Message text. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "truecoach_send_message",
    "arguments": {
      "client_id": "4821907",
      "body": "Hi Sam, Tuesday's lower body and Thursday's intervals slipped this week. Busy stretch or something else? Tell me and I'll adjust next week."
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "sent": 1,
    "client_id": "4821907",
    "sent_at": "2026-10-11T09:30:00+02:00"
  },
  "isError": false
}
```