Skip to main content
Glama
MONS MCP server

MONS MCP server

by tomis3
README.md
# MONS MCP server

The MCP server behind **MONS for Claude**: it lets a MONS coach build and adjust
their clients' training plans by chatting with an AI assistant. Ask in plain
words, and the assistant reads your clients' plans and your exercise library,
then makes the change in MONS. Your athletes see it in the app straight away.

- Hosted at **`https://mcp.mons.training/mcp`** (Streamable HTTP, OAuth 2.1)
- For **coaches only**: you sign in with your own MONS coach account
- Docs for coaches: <https://mons.training/claude>

This repository is published so coaches and their clients can see exactly what
the server does with their data. You do not need to run it yourself: connect to
the hosted address above. See [License](#license).

## Connect

You need a MONS coach account. Every app signs you in through MONS and asks you
to allow the connection; nothing else is set up.

### Claude (web, desktop and mobile)

1. Open **Settings → Connectors**.
2. Choose **Add custom connector**.
3. Paste `https://mcp.mons.training/mcp` and choose **Connect**.
4. Sign in with your MONS coach account and choose **Allow**.

A connector added on claude.ai is also available in the Claude desktop and
mobile apps.

### Claude Code

```bash
claude mcp add --transport http mons https://mcp.mons.training/mcp
```

Then run `/mcp` in Claude Code and sign in when asked.

### Other MCP clients

Any client that supports remote MCP servers with OAuth can use the address
directly. For a client that only starts local (stdio) servers, bridge to the
hosted server with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote),
which signs you in through your browser on `localhost`:

```json
{
  "mcpServers": {
    "mons": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.mons.training/mcp"]
    }
  }
}
```

### ChatGPT

Not available yet. The MONS sign-in currently accepts Claude, Claude Code and
local (`localhost`) clients only; ChatGPT support will be announced in the
[release notes](https://mons.training/release-notes).

## Try asking

- "Show me Jana Nováková's training for the next two weeks."
- "Build Eva Horáková a 3-week strength plan, 3 days a week, starting next Monday, and put it on her calendar."
- "For Jana, replace back squat with goblet squat in all her upcoming sessions."
- "In my Hypertrophy A template, add one set to every press."

## Tools

| Tool | What it does | Changes data |
| --- | --- | --- |
| `list_clients` | Your active clients, their programs and next session | no |
| `get_client_plan` | A client's sessions in a date range, with every exercise, set, rep, weight and note | no |
| `search_exercises` | Find an exercise in your library by name | no |
| `list_templates` | Your reusable workout templates | no |
| `get_template` | A template's weeks, days, exercises and sets | no |
| `list_programs` | Your group and fixed programs, with member counts | no |
| `get_program` | The sessions of a group or fixed program | no |
| `create_client_plan` | Put a new plan on one client's calendar from a start date | yes |
| `create_template` | Save a plan as a reusable template, not assigned to anyone | yes |
| `apply_template` | Copy a template onto a client's calendar from a start date | yes |
| `replace_exercise` | Swap one exercise for another, keeping the sets and targets | yes (destructive) |
| `update_exercise_targets` | Change sets, reps, weight, RPE, rest, tempo or coach notes | yes (destructive) |
| `add_exercise` | Add an exercise to upcoming sessions, a template or a program | yes |
| `remove_exercise` | Take an exercise out of upcoming sessions, a template or a program | yes (destructive) |

Every tool carries a `title` and `readOnlyHint` / `destructiveHint`
annotations, so your assistant can show each change and ask for your approval
before making it. (Clients that let you auto-approve tools skip that prompt;
leave it off if you want to confirm each change.)

## What it will and won't do

- Changes only touch sessions that have not started. Sessions a client has done
  or begun, and every logged set, are never changed.
- Editing a template does not change clients who already have that template on
  their calendar.
- An ambiguous name (two clients called Jana, an exercise that is only close to
  what you typed) is answered with the candidates, never guessed.
- It sees only what you can already see in MONS, through these tools: your
  clients, your templates, your programs. No other coach's data.
- It has no access to readiness, body measurements, nutrition, chat messages or
  payment details.

## How it works

```
AI client ──OAuth 2.1──▶ MONS sign-in (Supabase Auth OAuth server, consent at coach.mons.training)
    │
    └─Streamable HTTP──▶ Cloudflare Worker (src/) ──PostgREST RPC, coach's own token──▶ mons.mcp_* SQL functions (sql/)
```

- **Auth** (`src/auth.ts`): ES256 access tokens are verified against the MONS
  project's JWKS. The token must be issued to an OAuth client (`client_id`
  claim) and belong to a coach; client (athlete) accounts are refused.
- **No privileged key in the server.** The Worker calls the database with the
  public anon key plus the coach's own token, so every row is filtered by the
  same row-level security as the MONS coach web app.
- **SQL** (`sql/`): the tools are thin wrappers over `mons.mcp_*` Postgres
  functions running as the caller (`security invoker`). Each write is one
  atomic call; the past/started/completed-session rule is enforced there.
- **Token scope** (`sql/20261107*`): a token issued to an AI client can call
  only the 17 functions the Worker uses, not the rest of the MONS API.
- **Logs** (`src/index.ts`): one line per request with the route, status,
  coach id, tool name, outcome and duration. Never arguments, client names,
  notes or weights.

The `sql/` folder is a copy of the MONS database migrations that define these
functions, published for review; they are applied to the MONS project, not run
from here.

## Development

```bash
npm ci
npm test           # unit tests (no network)
npm run typecheck
```

The integration tests and the demo-account seed run against the live MONS
project and live in the private MONS repository.

## Privacy, support, security

- Privacy Policy: <https://mons.training/MONS%20Privacy%20Policy> (section "Claude Connector")
- Terms of Service: <https://mons.training/MONS%20Terms%20of%20Service>
- Support: hello@mons.training
- Security issues: see [SECURITY.md](SECURITY.md)

To disconnect, remove the MONS connector in your client (claude.ai: Settings →
Connectors; Claude Code: `claude mcp remove mons`). To have MONS revoke the
connection on its side as well, write to hello@mons.training.

## License

Source-available, **all rights reserved**. See [LICENSE](LICENSE). The hosted
server at `mcp.mons.training` is provided by LifeAnalytics s.r.o.