# Connect AI apps with MCP

CloudFit has an MCP server, so AI apps such as Claude and ChatGPT can work with your CloudFit locations: read and build workouts, find exercises, manage the exercise and media libraries, and plan the class schedule. You ask in plain language and the app calls CloudFit for you.

> The CloudFit API is in Beta and needs the Business plan. Owners, HQ owners and staff can connect; an app can never do more than you can do in CloudFit yourself.

## The server URL

```
https://api.cloudfit.tv/mcp
```

Every app below uses this URL. You sign in to CloudFit in your browser and choose what the app may do; you never handle a password or token.

## Connect an app

### Claude (web, desktop and mobile)

The quickest way: open [CloudFit in Claude’s directory](https://claude.ai/directory/cloudfit) and select **Connect**. A directory connector doesn’t count toward the Free plan’s one custom connector.

Or add it yourself:

1. In Claude, go to **Customize → Connectors**, select **Add**, then **Add custom connector**.
2. Name it CloudFit, paste `https://api.cloudfit.tv/mcp` as the URL and select **Continue**. Keep the sign-in settings Claude detects.
3. Select **Add**, then **Connect**. A CloudFit page opens: sign in, pick the locations and whether Claude may only read or also make changes, then approve.
4. In a chat, turn CloudFit on under **+ → Connectors**.

On a Team or Enterprise plan, an owner adds the connector once under **Organization settings → Connectors**, and each person then connects with their own CloudFit account. On the Free plan Claude allows one custom connector.

To check it works, ask: “Which CloudFit locations can you see, and what can you do at each?” It should list the locations you ticked, with your role and whether it can make changes. If a location is missing or it can only read, disconnect and connect again with the access you want.

### ChatGPT

ChatGPT connects to MCP servers as plugins, on the web.

1. Open [ChatGPT Plugins](https://chatgpt.com/plugins), select **+**, then **Add custom MCP server**.
2. Name it CloudFit and enter `https://api.cloudfit.tv/mcp` as the **Server URL**.
3. Under authentication choose **OAuth**, read the warning and continue, then select **Create as a plugin**.
4. Install the plugin from your plugins. A CloudFit page opens: sign in, pick locations and access, and approve.
5. In a chat, type **@** and pick CloudFit, then ask the same check: “Which CloudFit locations can you see, and what can you do at each?”

If **Add custom MCP server** isn’t there, your plan or workspace may not allow custom servers yet; a workspace admin may need to turn it on. OpenAI describes the steps in [Add a custom MCP server](https://developers.openai.com/api/docs/guides/custom-mcp-server).

To add exercise videos or images in ChatGPT, attach them to the chat and ask, for example, “Add these as exercises.” CloudFit fetches the attached files itself, so there’s no link to open. This works in ChatGPT on the web; if the phone app can’t pass the files on, ChatGPT gives you the upload page instead. Before adding them, the AI suggests a name, equipment and categories for each one for you to check, and asks before your video replaces one of CloudFit’s built-in exercises.

### Claude Code

```bash
claude mcp add --transport http cloudfit https://api.cloudfit.tv/mcp
```

Then run `/mcp` in Claude Code, pick **cloudfit** and choose **Authenticate**. Your browser opens the CloudFit page; it warns that the app runs on your computer, which is expected for Claude Code.

### Codex

```bash
codex mcp add cloudfit --url https://api.cloudfit.tv/mcp
```

```bash
codex mcp login cloudfit
```

The login opens the CloudFit page in your browser, as for Claude Code.

### Other MCP clients and scripts

Signing in with CloudFit works for Claude, Claude Code, ChatGPT and Codex. Any other MCP client can use a personal token instead: create one in the CloudFit app under **Settings → AI & API Access**, then send it as a header, `Authorization: Bearer cf_api_live_…`. Treat it like a password. The [technical guide](/docs/guide) explains tokens and scopes.

## What you approve

- **Locations:** only the ones you tick. Each location gets read-only access or read-and-change access.
- **Never more than you have:** an app’s access is checked against your CloudFit permissions on every call, so if your role changes, the app’s access changes with it.
- **Staying connected:** the app stays signed in while it’s used at least every 90 days. You can have up to 10 connected apps; connecting another disconnects the one used least recently.
- **Read only, or read and change:** read-and-change lets the app create, edit and delete workouts and exercises, plan the schedule, upload media and, if you’re the owner, publish workouts on a public web page. Choose read only if you just want answers.
- **Disconnecting:** in the CloudFit app, open **Settings → AI & API Access** and disconnect it under connected apps. It stops working straight away. Removing CloudFit in the AI app as well tidies up there, but the CloudFit app is what cuts access.
- **Changing access:** to give an app more (another location, or changes instead of read-only), remove CloudFit in the AI app and connect again.

## Things to ask

- “What workouts does Main Street have in the Strength folder?”
- “Build a 45-minute kettlebell HIIT workout and save it to the Conditioning folder.”
- “Create a split-room workout: HIIT on TVs 1–3 and strength on TVs 4–6.”
- “Copy HQ’s Saturday Bootcamp into our location and swap burpees for squat jumps.”
- “Schedule Strength 101 every weekday at 6:00 am Melbourne time until the end of March.”
- “Replace the next four weeks’ timetable with a copy of this week.”
- “Add an exercise called Sled Push and give me a link to upload its video.”
- “Use this photo as the whiteboard background in Friday Finisher.”
- “Publish Friday Finisher so members can do it at home, until the end of January.” (owners only)

When you add videos or images, the app usually gives you a link: open it in your browser and choose the files from your computer or phone. In ChatGPT you can attach exercise videos and images to the chat instead. If your AI app asks to allow other websites to get at your files, you can say no and use the link instead.

## What it can’t do

An AI app connected to CloudFit works with workouts, exercises, media, the class schedule and published workouts. It can’t press start or stop on your displays, control the TVs, manage members or bookings, or change billing. But what it changes does reach the TVs: classes it schedules start on their own at their time, and a workout it edits plays the new version the next time it starts.

At an HQ, changes reach every location that uses the HQ’s library: editing or deleting an HQ workout or exercise changes it for them too.

## How changes stay safe

CloudFit enforces these itself, whatever the app does:

- **Nothing is overwritten by accident.** Editing, deleting or publishing a workout names the version of it the app read. If someone changed the workout in the meantime, it’s refused and the app reads it again.
- **Schedule batches are all or nothing.** A batch that would remove or change classes needs the revision from its preview, so it can’t be applied blind.
- **Retries don’t double up.** Creating, copying, editing a workout and applying schedule changes take a request key; a retry with the same key returns the first result instead of acting twice.

And CloudFit tells the app to do these, which good apps do:

- **Show the preview first.** Workout edits and schedule changes are previewed before they’re applied, and the app should show you what would change, especially anything removed, before going ahead.
- **Ask before deleting or publishing.**

Limits that also apply:

- **Deleting is limited.** An app can archive a workout, which you can undo in CloudFit, and it can only archive or delete a few a day. A workout with upcoming classes isn’t deleted, and CloudFit support can recover a deleted workout. Deleting a custom exercise can’t be undone: it’s taken out of every workout that uses it, so the app should show you which first. That list is how things stood when the app checked; the delete itself doesn’t check it again. CloudFit support can put back schedule changes.
- **Publishing is the owner’s.** Only the location’s owner can publish a workout for customers or take it down, as in the app, and the app should ask you first: publishing puts it on a public web page.
- **Copies, not edits, of HQ workouts.** A location’s HQ library is read-only; an app copies an HQ workout into the location to change it.

## Tools

The server offers these tools. Your app picks them; you don’t need to name them. “Needs” is the access the tool uses: read scopes come with any connection, and change scopes need read-and-change access and the matching CloudFit permission. Previews and upload checks change nothing but need change access, since they’re steps of a change. `report_missing_capability` lets the app send CloudFit a short note about something you asked for that it can’t do yet. The app is told to ask you first, show you the note, and describe only the missing feature, without workout details, exercise lists, links or names.

### Locations

| Tool | What it does | Access | Needs |
| --- | --- | --- | --- |
| `list_locations` | List locations | Reads only | any access |
| `get_location` | Get a location | Reads only | `locations:read` |
| `report_missing_capability` | Tell CloudFit about a missing feature | Changes | any access |

### Workouts and folders

| Tool | What it does | Access | Needs |
| --- | --- | --- | --- |
| `list_workout_history` | List workout history | Reads only | `workouts:read` |
| `list_folders` | List folders | Reads only | `workouts:read` |
| `create_folder` | Create a folder | Changes | `workouts:write` |
| `list_workouts` | List workouts | Reads only | `workouts:read` |
| `get_workout` | Get a workout | Reads only | `workouts:read` |
| `validate_workout` | Validate a workout spec | Reads only | `workouts:read` |
| `create_workout` | Create a workout | Changes | `workouts:write` |
| `duplicate_workout` | Duplicate a workout | Changes | `workouts:write` |
| `preview_workout_edits` | Preview workout edits | Reads only | `workouts:write` |
| `apply_workout_edits` | Apply workout edits | Changes; can replace or remove | `workouts:write` |
| `delete_workout` | Delete a workout | Changes; can replace or remove | `workouts:write` |
| `publish_workout` | Publish a workout | Changes; can replace or remove | `workouts:write` |
| `unpublish_workout` | Unpublish a workout | Changes; can replace or remove | `workouts:write` |

### Exercises

| Tool | What it does | Access | Needs |
| --- | --- | --- | --- |
| `list_custom_exercises` | List custom exercises | Reads only | `exercises:read` |
| `create_exercise` | Create an exercise | Changes | `exercises:write` |
| `create_exercise_upload` | Create an exercise media upload link | Changes | `exercises:write` |
| `get_exercise_upload` | Check an exercise media upload | Reads only | `exercises:write` |
| `create_exercise_import` | Start an exercise import | Changes | `exercises:write` |
| `add_exercise_import_files` | Add files to an exercise import | Changes | `exercises:write` |
| `add_exercises_from_files` | Add exercises from attached files (ChatGPT only) | Changes | `exercises:write` |
| `get_exercise_import` | Check an exercise import | Reads only | `exercises:write` |
| `rename_exercises` | Rename exercises | Changes; can replace or remove | `exercises:write` |
| `update_exercises` | Update exercises | Changes; can replace or remove | `exercises:write` |
| `get_exercise_usage` | Show where an exercise is used | Reads only | `exercises:read` |
| `delete_exercise` | Delete an exercise | Changes; can replace or remove | `exercises:write` |
| `get_exercise_download_links` | Get exercise download links | Reads only | `exercises:read` |
| `search_exercises` | Search exercises | Reads only | `exercises:read` |

### Media

| Tool | What it does | Access | Needs |
| --- | --- | --- | --- |
| `list_media` | List media | Reads only | `media:read` |
| `create_media_upload` | Create a media upload link | Changes | `media:write` |
| `get_media_upload` | Check a media upload | Reads only | `media:write` |

### Schedule

| Tool | What it does | Access | Needs |
| --- | --- | --- | --- |
| `list_schedule` | List the schedule | Reads only | `schedule:read` |
| `preview_schedule_changes` | Preview schedule changes | Reads only | `schedule:write` |
| `apply_schedule_changes` | Apply schedule changes | Changes; can replace or remove | `schedule:write` |

## Limits

The limits are generous for building workouts and planning schedules, and slow down bulk copying. When a per-minute or daily limit is reached, the tool error says how long to wait (`retryAfterSeconds`), and the app can try again then. The bulk import allowance works differently: when it’s used up, adding files says so (`exercise_import_limit_reached`) with how many remain and when room frees up (`details.remaining`, `details.nextFreesAt`).

| Limit | Allowance |
| --- | --- |
| Every request or tool call | 120 a minute per token or connected app, and 240 a minute per person across all of them |
| Validating and previewing, listing media, exercise downloads | 60 a minute per person |
| Changes (create, duplicate, apply edits, publish, schedule changes, uploads, folders, exercises) | 30 a minute per person and 30 a minute per location |
| Exercise searches | 200 a day per person |
| Workouts archived | 10 a day per location (unarchiving isn’t limited) |
| Workouts deleted | 10 a day per location |
| Workouts published, updated or unpublished | 30 a day per location |
| Exercises created | 50 a day per location |
| Exercises imported (bulk import) | 200 per location in any 7 days; CloudFit can raise it for a larger library |
| Exercises renamed | 50 a day per location |
| Exercises updated (equipment, categories) | 200 a day per location |
| Exercises deleted | 20 a day per location |
| Exercises given download links | 200 a day per location |

## Troubleshooting

- **`scope_missing`:** the app was approved for reading only, or for other locations. Disconnect it in the AI app and connect again with the access it needs.
- **`permission_denied`:** your CloudFit role doesn’t allow that change at that location.
- **`rate_limited`:** a limit above was reached; the error says when to try again.
- **`writes_paused`:** CloudFit has paused changes through the API for a while. Reading still works.
- **New tools don’t appear:** AI apps load the tool list when they connect. In ChatGPT, open the plugin’s details and refresh it; elsewhere reconnect, or start a new chat.
- **Asked to sign in again:** connecting may ask you to sign in to CloudFit again. That’s expected.
- **Upload link expired:** single-file upload links last 30 minutes, and a bulk import page 24 hours; ask the app for a new one (a new import page stops the old one working).
- **Upload failed:** the app says why. A file that’s too big, too long, portrait or the wrong type needs a different file; “too many videos processed recently” means wait and try later; a permission or missing-exercise failure won’t be fixed by uploading again.

Every error has a stable code; the full list is in the [technical guide](/docs/guide#errors).