# GymStack per MCP verbinden

> GymStack ist ein First-Party-MCP-Server: Externe KI-Agents bedienen das Studio durch dieselbe Sicherheitskette wie die eingebauten Agents. Quelle: https://gymstack.de/mcp/

## Endpunkt

- `POST https://intent-finch-948.eu-west-1.convex.site/mcp` (Stateless Streamable-HTTP, Antworten als `application/json`)

## Verbinden

### OAuth-Connector (claude.ai / ChatGPT)

Endpunkt als Custom Connector hinzufügen — Discovery nach RFC 9728: https://intent-finch-948.eu-west-1.convex.site/.well-known/oauth-protected-resource. Der Betreiber meldet sich an und bestätigt sein Studio; kein Schlüssel nötig. Scopes: read + propose.

### API-Schlüssel (Claude Code, Cursor, n8n, Messages-API)

Ein Admin erstellt den Schlüssel in der GymStack-Konsole unter *Einstellungen → Integrationen (MCP)* (max. 10 pro Studio, Klartext einmalig, jederzeit widerrufbar). Header: `Authorization: Bearer gsk_<64hex>`.

```bash
claude mcp add gymstack --transport http https://intent-finch-948.eu-west-1.convex.site/mcp \
  --header "Authorization: Bearer gsk_…"
```

## Sicherheitsmodell

- Schreibzugriffe werden nie direkt ausgeführt: Jeder Schreibwunsch wird ein Vorschlag in der Freigabe-Queue des Studios und erst nach menschlicher Freigabe umgesetzt (propose-only).
- Lesende Tools liefern Daten direkt; jeder Zugriff wird pro Studio auditiert (inkl. Schlüssel-Kennung).
- Rate-Limits: 60 Anfragen/Min pro Schlüssel (HTTP 429), 30 Vorschläge/Std.

## Tools nach Agent

Rund 50 Tools nach dem Schema `{agent}_{tool}`:

### Cleo — Studio-Überblick & KPIs

Kennzahlen-Zusammenfassung, Mitglieder-Suche, offene Freigaben, Risiko-Überblick und Berichte — nur lesend.

Beispiele: `cleo_kpi_summary`, `cleo_run_report`

### Mia — Marketing

Kampagnen-, Budget- und Social-Überblick, Angebote & Aktionscodes; Vorschläge für Budget-Umschichtungen, Posts und Angebote.

Beispiele: `mia_campaign_summary`, `mia_propose_budget_reallocation`

Details zur Persona: https://gymstack.de/agents/marketing/

### Leo — Leads

Funnel- und Lead-Überblick; Termin-Vorschläge für Probetrainings.

Beispiele: `leo_lead_summary`, `leo_propose_appointment`

Details zur Persona: https://gymstack.de/agents/lead/

### Emma — Retention

At-Risk-Mitglieder, Segmente und Buddy-Pass-Status; Winback-, Onboarding- und Angebots-Vorschläge.

Beispiele: `emma_at_risk_members`, `emma_propose_winback`

Details zur Persona: https://gymstack.de/agents/retention/

### Sofia — Support

Konversationen durchsuchen und lesen; Antwort-Entwürfe für den Posteingang.

Beispiele: `sofia_search_conversations`, `sofia_draft_reply`

Details zur Persona: https://gymstack.de/agents/support/

### Finn — Billing

Verträge, Zahlungen, SEPA-Läufe, Mahnwesen und Rechnungen; Vorschläge für Verträge, Zahlungserinnerungen und Rechnungsversand.

Beispiele: `finn_search_members`, `finn_payment_summary`

Details zur Persona: https://gymstack.de/agents/billing/

### Klara — Finance

Umsatzberichte, Forecast, Monats-KPIs und Umsatz nach Zahlungsart — nur lesend.

Beispiele: `klara_revenue_report`, `klara_kpi_overview`

Details zur Persona: https://gymstack.de/agents/finance/

### Otto — Operations

Anwesenheit, Kursplan, Auslastung und Dienstplan; Kurs-, Schicht- und Tageskarten-Vorschläge.

Beispiele: `otto_schedule_overview`, `otto_propose_class`

Details zur Persona: https://gymstack.de/agents/operations/

### Max — Facility

Offene Facility-Meldungen; Wartungs-Vorschläge.

Beispiele: `max_open_facility_reports`, `max_propose_maintenance`

Details zur Persona: https://gymstack.de/agents/facility/

## FAQ

**Was ist der GymStack-MCP-Server?** MCP (Model Context Protocol) ist ein offener Standard, über den KI-Assistenten wie Claude oder ChatGPT die Tools eines Dienstes nutzen können. GymStack stellt rund 50 Tools bereit, mit denen externe Agents dein Studio bedienen — durch dieselbe Sicherheitskette wie die eingebauten GymStack-Agents.

**Kann ein externer Agent etwas kaputtmachen?** Nein. Schreibzugriffe werden nie direkt ausgeführt: Jeder Schreibwunsch landet als Vorschlag in deiner Freigabe-Queue („Braucht dich") und wird erst nach deiner Freigabe umgesetzt. Lesende Tools liefern Daten direkt.

**Welche Clients werden unterstützt?** claude.ai und ChatGPT verbinden sich per OAuth-Connector (ohne Schlüssel). Claude Code, IDEs wie Cursor, n8n und die Anthropic Messages-API nutzen einen API-Schlüssel.

**Wo erstelle ich einen API-Schlüssel?** In der GymStack-Konsole unter Einstellungen → Integrationen (MCP). Maximal 10 aktive Schlüssel pro Studio; der Klartext wird genau einmal angezeigt. Schlüssel lassen sich jederzeit widerrufen.

**Was kostet der MCP-Zugang?** Nichts extra — er ist im Abo enthalten. Fair-Use-Limits: 60 Anfragen pro Minute und 30 Vorschläge pro Stunde je Schlüssel.

**Werden Zugriffe protokolliert?** Ja. Jeder Zugriff läuft über dein Studio-Konto bzw. deinen Schlüssel und wird im Audit-Log festgehalten, inklusive Schlüssel-Kennung bei API-Key-Zugriffen.

## Maschinenlesbare Dateien

- Authentifizierung (englisch): https://gymstack.de/auth.md
- API-Katalog (RFC 9727): https://gymstack.de/.well-known/api-catalog
- MCP Server Card: https://gymstack.de/.well-known/mcp/server-card.json
- OAuth Protected Resource Metadata (RFC 9728): https://intent-finch-948.eu-west-1.convex.site/.well-known/oauth-protected-resource