Zum Hauptinhalt gehen

Sport Alliance MCP einrichten und nutzen

  • Aktualisiert

In diesem Artikel lernst du …

  • was der Connector kann und welche AI-Apps ihn unterstützen
  • wie du ihn Schritt für Schritt in einer Sandbox einrichtest
  • welche Berechtigungsstufen es gibt und wie du sie steuerst
  • wie du vom Sandbox-Test in den Produktivbetrieb wechselst
  • was die häufigsten Meldungen bedeuten

Inhalt

Schnellanleitung

  1. Auf developer.sportalliance.com registrieren und ein Partner-Konto anlegen.
  2. Marke wählen, Sandbox-Zugangsdaten anfordern und 2 bis 3 Minuten warten.
  3. Application anlegen und ihr die benötigten Scopes zuweisen.
  4. Im Sandbox-Studio die Integration aktivieren und dabei alle Freigabe-Kästchen setzen.
  5. uv im Terminal installieren.
  6. Aktivierungs-Mail öffnen, PDF mit dem Passwort aus dem Portal öffnen, Mandantenname und Schlüssel bereitlegen.
  7. uvx sportalliance-mcp setup ausführen und den Fragen des Assistenten folgen.
  8. AI-App neu starten und mit einer einfachen Frage testen.

Was der Connector kann

Der Connector verbindet einen AI-Assistenten mit Magicline oder PerfectGym Next. Du stellst deine Anfrage in normaler Sprache, der Connector übersetzt sie in geprüfte und berechtigungsgesteuerte Aktionen und liefert dir die Antwort zurück. Programmieren musst du dafür nicht.

Unterstützt werden Claude Desktop, Claude Code, Cursor, Windsurf, Gemini CLI und Antigravity.

So sehen typische Anfragen aus:

  • „Buch Jonas Weber in den Spin-Kurs heute Abend."
  • „Check Anna Schmidt ein."
  • „Pausiere Annas Vertrag für August, Urlaub."
  • „Welche Kurse laufen morgen, welche haben noch freie Plätze?"
  • „Welche Mitgliedschaftsangebote verkaufen wir, was würde Premium für Kunde 10023 kosten?"

Eine einzige Installation kann beide Plattformen gleichzeitig bedienen. Verschiedene Studios und Konten laufen nebeneinander, jeweils mit eigenem Schlüssel und eigenen Berechtigungen.

Der Connector gilt für Magicline und PerfectGym Next. Für das klassische PerfectGym-Produkt unter perfectgym.pl funktioniert er nicht, das ist ein anderes System.

Voraussetzungen

  • Eine der oben genannten AI-Apps
  • Ein Terminal-Fenster: die Terminal-App auf dem Mac, PowerShell unter Windows
  • Ein E-Mail-Postfach, denn der Zugangsschlüssel kommt per Mail
  • Rund 30 Minuten Zeit, einmalig

Alle Schritte in Teil A bis C laufen in einer Sandbox, also in einer eigenen Test-Umgebung ohne echte Daten. Erst Teil D führt in den Produktivbetrieb.

Berechtigungen und Schutzmechanismen

Der Connector arbeitet mit drei Zugriffsstufen. Er startet immer auf Stufe 1, höhere Stufen musst du aktiv einschalten.

  1. Nur lesen (Standard, immer aktiv): Kurspläne, freie Plätze, Mitgliedschaftsangebote und Studio-Informationen. Keine Mitgliederdaten, und nichts lässt sich verändern.
  2. Mitgliederdaten (Opt-in): Profile, Verträge, Kontostände und Check-in-Historie. Das sind echte persönliche Daten echter Mitglieder, schalte die Stufe also nur ein, wenn du dafür bereit bist.
  3. Änderungen vornehmen (Opt-in): Kurse buchen, Mitglieder einchecken, Interessenten anlegen, Verträge pausieren. Das sind echte Aktionen im Studio, und der Assistent zeigt dir vorher immer, was er vorhat.

Vier Schutzmechanismen sind unabhängig von der gewählten Stufe immer aktiv:

  • Kritische Aktionen wie eine Vertragskündigung, ein Mitgliedschaftsabschluss oder ein Export von Finanzdaten werden nie automatisch durchgewunken. Ein Mensch bestätigt jede einzelne.
  • Jede Antwort nennt das Studio, aus dem sie stammt, mit klarer Kennzeichnung als PRODUCTION oder Sandbox.
  • Die Identität wird bei jedem Start neu geprüft. Passt etwas nicht zusammen, startet der Connector lieber gar nicht, statt zu raten.
  • Der Schlüssel liegt im Schlüsselbund deines Rechners, also in der macOS Keychain oder im Windows Credential Manager, nie in einer Klartext-Datei.

Wenn ein Zugangsschlüssel versehentlich geteilt wurde, etwa in einem Chat, einem Screenshot oder einem Ticket, stelle ihn im Portal neu aus.

Teil A: Application im Developer-Portal anlegen

Teil A läuft komplett im Developer-Portal unter developer.sportalliance.com.

  1. Registriere dich auf developer.sportalliance.com, entweder mit E-Mail und Passwort oder mit Google. Wenn du noch kein Konto hast, findest du Register here unterhalb des Login-Buttons.

Login-Seite des Developer-Portals mit dem Link Register here unter dem Login-Button

  1. Beim ersten Login entscheidest du, zu welcher Organisation du gehörst. Hat deine Firma schon ein Partner-Konto, bitte den Administrator um Zugang. Andernfalls wähle Create New Partner Account, gib Partner-Name und Firmenname ein, akzeptiere die AGB und speichere mit Save.

Willkommensbildschirm beim ersten Login mit der Auswahl Create New Partner Account

Formular für Partner-Name, Firmenname und AGB-Haken

  1. Wähle im Marken-Dropdown oben die passende Marke, also Magicline oder PerfectGym. Öffne dann Sandbox / Details und klicke auf Request Sandbox Credentials. Nach 2 bis 3 Minuten steht dein eigenes Test-Studio bereit, vollständig getrennt von echten Daten.

Sandbox-Details vor der Bereitstellung, ein Klick startet sie

  1. Öffne Sandbox / Applications und klicke auf Add New Application.

Übersicht Sandbox Applications mit dem Button Add New Application

  1. Wähle im Dialog den Application-Typ Generic, gib einen Namen ein, zum Beispiel „MCP", und trage die Aktivierungs-E-Mail-Adresse ein. An diese Adresse geht später die Aktivierungs-Mail mit Mandantenname und Zugangsschlüssel. Der Schlüssel steckt in einem passwortgeschützten PDF, das Passwort dazu findest du im Portal.

Dialog zum Anlegen einer Application mit Typ Generic, Name und Aktivierungs-E-Mail-Adresse

  1. Öffne die neue Application, wechsle auf den Tab Scopes und klicke auf Add Scopes. Scopes kommen paarweise als _READ und _WRITE pro Bereich, zum Beispiel für Termine, Check-in, Kurse und Kundendaten. Für die Sandbox ist Select All praktisch, für den Produktivbetrieb vergibst du besser gezielt.

Frische Application ohne zugewiesene Scopes und damit ohne Zugriff

Scope-Auswahl mit READ- und WRITE-Paaren pro Bereich

Die hier gewählten Scopes sind die absolute Obergrenze dessen, was der Connector je erreichen kann, unabhängig davon, was du den Assistenten fragst. Wähle sparsam, erweitern kannst du später jederzeit.

Teil B: Integration im Studio aktivieren

  1. Auf Sandbox / Details stehen jetzt deine Zugangsdaten bereit: die Web-Adresse (https://<mandant>.web.sandbox.magicline.com für Magicline, https://<mandant>.web.sandbox.perfectgym.com für PerfectGym Next), der Benutzername adminuser, das Passwort, das du über das Augen-Symbol sichtbar machst, und die Basis-URL (https://<mandant>.open-api.sandbox.magicline.com beziehungsweise https://<mandant>.open-api.sandbox.perfectgym.com). Melde dich mit Benutzername und Passwort an.

Sandbox-Details mit Zugangsdaten nach abgeschlossener Bereitstellung

  1. Gehe im Studio auf Settings / Integrations / Overview. Dort erscheint deine eigene Application neben den eingebauten Partnern. Klicke in ihrer Zeile auf Activate.

Integrationsübersicht im Studio mit der eigenen Application und dem Activate-Button

Der Aktivierungsdialog fragt, welche Kundendaten das Studio mit der Integration teilt, in zwei Gruppen: bestehende Kunden (Mitglieder, Interessenten, ehemalige Mitglieder) und neue Kunden (neue Mitglieder, neue Interessenten), insgesamt fünf Freigabe-Kästchen. Standardmäßig ist alles aus. Setze alle fünf Kästchen und klicke erst danach auf Activate, sonst sieht der Connector ein leeres Studio. Anschließend erhältst du die Aktivierungs-Mail mit Mandantenname und Schlüssel.

Consent-Schritt der Aktivierung mit den Freigabe-Kästchen zur Datenweitergabe

Teil C: Connector im Terminal einrichten

  1. Installiere uv. Das bringt eine eigene Python-Umgebung mit, mehr brauchst du nicht.
    • macOS und Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
    • Windows PowerShell: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  2. Öffne die Aktivierungs-Mail und darin das PDF mit dem Passwort aus dem Portal. Halte Mandantenname und Schlüssel bereit.
  3. Führe uvx sportalliance-mcp setup aus. Der Assistent fragt zuerst nach der Plattform und bietet dazu Magicline und PerfectGym Next zur Auswahl an.
  4. Gib den Mandantenname ein und wähle die Umgebung: Sandbox für das Test-Studio aus Teil B, Production für den Echtbetrieb. Jede Option zeigt dir die vollständige API-Adresse zur Kontrolle. Füge dann den Schlüssel aus dem PDF ein, die Eingabe wird dabei nicht angezeigt. Der Assistent prüft den Schlüssel live gegen die API und zeigt dir, welches Studio er tatsächlich öffnet. Der Server startet standardmäßig im sicheren Nur-Lesen-Modus, und der Schlüssel landet im Schlüsselbund deines Betriebssystems.
  5. Optional folgt die Frage nach einer Datawarehouse-Anbindung. Das ist eine erweiterte Funktion für Enterprise-Kunden mit eigenem Datawarehouse-Zugang, Details dazu stehen in der technischen Dokumentation. Ohne diesen Zugang überspringst du die Frage mit Enter, es ändert sich dann nichts.
  6. Wähle zum Schluss die AI-Apps aus, die eingerichtet werden sollen. Bereits erkannte Apps sind vorausgewählt, du bestätigst mit Enter. Bei Claude Code kommt zusätzlich die Frage, wie viel vorab freigegeben werden soll. Empfohlen ist: nicht-persönliche Lese-Tools laufen ohne Rückfrage, Mitgliederdaten und Änderungen fragen weiterhin nach.

Danach ist die Einrichtung fertig. Starte die AI-App neu, dann stehen die Tools bereit.

Einrichtung testen

Starte die AI-App neu und stelle eine einfache Frage, zum Beispiel „Welche Kurse stehen morgen auf dem Plan?". Kommt eine Antwort aus deinem Studio zurück, antworten die Tools wie gewünscht.

Teil D: In den Produktivbetrieb wechseln

Sobald die Sandbox wie gewünscht funktioniert, wiederholst du dieselben Schritte für Application, Details und Scopes im Portal-Tab Production und reichst die Application zur Prüfung ein.

Bei den Scopes bist du hier besonders sorgfältig: Was du vergibst, gilt für jedes Studio, das die Integration aktiviert.

Nach der Freigabe durch Sport Alliance können echte Studios die Integration genauso aktivieren wie in Schritt 8. Die Aktivierung liefert wieder einen Schlüssel per passwortgeschütztem PDF. Führe dann uvx sportalliance-mcp setup erneut aus, diesmal mit dem Produktiv-Mandanten und dem Produktiv-Schlüssel, und wähle als Umgebung Production.

Der Connector im Alltag

Am Empfang:

  • „Buch Jonas Weber in den Spin-Kurs heute Abend."
  • „Check Anna Schmidt ein."
  • „Wann kann Anna ihren Vertrag spätestens kündigen?"
  • „Wie hoch ist ihr Kontostand, und was ist als Nächstes fällig?"
  • „Verlängere ihre Pause um einen Monat, was würde das kosten?"
  • „Leg einen Interessenten für Max Mustermann an, max@example.com, und buch ihm morgen früh eine kostenlose Probestunde."

Im Backoffice:

  • „Wie voll ist das Studio gerade?"
  • „Welche Kurse laufen morgen, welche haben noch freie Plätze?"
  • „Zeig den Kontostand und die anstehenden Belastungen für Kunde 10023."
  • „Vermerk das Telefonat bei ihm."

Vor jeder Buchung und jeder Vertragsänderung prüft der Assistent automatisch, ob die Aktion für dieses Mitglied überhaupt möglich ist. Eingeschränkte Kurse, Mitgliedschaftsregeln und Pausenlimits werden dabei automatisch beachtet.

Wenn ein Kurs oder ein Angebot „nicht existiert", wurde es meist im Backoffice noch nicht angelegt. Der Connector kann das bestehende Angebot lesen und buchen, neue Kurse und Angebote anzulegen bleibt eine Aufgabe im Backoffice.

Berechtigungen später anpassen

Der Befehl uvx sportalliance-mcp permissions genügt, um Zugriffsstufen an- oder auszuschalten oder einzelne Fähigkeiten gezielt zu deaktivieren, zum Beispiel Kursbuchung behalten, Vertragskündigung aber generell ausschließen. Die Einrichtung musst du dafür nicht erneut durchlaufen.

Nach jeder Änderung an den Einstellungen startest du die AI-App neu.

Häufige Meldungen und was sie bedeuten

  • „The tenant does not exist on this host": Sandbox- und Produktiv-Studios liegen unter unterschiedlichen Adressen. Dein Studio existiert, nur in der jeweils anderen Umgebung. Der Einrichtungsassistent bietet dir den Wechsel mit einem Tastendruck an.
  • „The key is valid, but the integration has no scope…": Der Schlüssel funktioniert, aber der Application wurden im Portal keine Berechtigungen zugewiesen. Gehe zurück zu Schritt 6, ergänze die Scopes und versuche es erneut.
  • „The API rejected the key (401/403)": Mandant und Schlüssel passen nicht zusammen. Beide stammen aus derselben Aktivierungs-Mail, prüfe sie dort noch einmal. Wenn du beide Plattformen nutzt, stelle sicher, dass der Schlüssel nicht von der jeweils anderen Plattform stammt.
  • Die Verbindung startet gar nicht und meldet „STOPPING": Der Schlüssel öffnet ein anderes Studio als das, für das diese Verbindung eingerichtet wurde. Das ist die Identitätsprüfung, die genau das verhindert. Durchlaufe den Einrichtungsassistenten für diese Plattform noch einmal.
  • Tools fehlen in der AI-App: Fähigkeiten für Mitgliederdaten und Änderungen erscheinen nur, wenn ihre Stufe eingeschaltet ist. Prüfe die Berechtigungen und starte die AI-App danach neu.
  • Die Daten eines Mitglieds kommen als „permission denied" zurück: Manche Mitglieder widersprechen der Datenweitergabe an Dritte. Das ist ihr Recht, die Plattform hält sich daran, und der Connector meldet das, statt es erneut zu versuchen.

Weitere Studios oder Plattformen anbinden

Wenn du zusätzliche Studios oder die jeweils andere Plattform anbinden willst, durchlaufe die Einrichtung einfach erneut. Beide laufen dann parallel in derselben AI-App und sind farblich voneinander unterschieden.

Hinweis: Dieser Artikel wurde mit Unterstützung von künstlicher Intelligenz erstellt und redaktionell geprüft.