Overslaan en naar hoofdcontent gaan

Sport Alliance MCP instellen en gebruiken

  • Bijgewerkt

In dit artikel leer je …

  • wat de connector kan en welke AI-apps hem ondersteunen
  • hoe je hem stap voor stap instelt in een sandbox
  • welke rechtenniveaus er zijn en hoe je ze beheert
  • hoe je van de sandboxtest naar live gebruik overstapt
  • wat de meest voorkomende meldingen betekenen

Inhoud

Snelgids

  1. Registreer je op developer.sportalliance.com en maak een partneraccount aan.
  2. Kies je merk, vraag sandbox-inloggegevens aan en wacht 2 tot 3 minuten.
  3. Maak een applicatie aan en wijs er de nodige scopes aan toe.
  4. Activeer de integratie in de sandboxstudio en zet alle toestemmingsvakjes aan.
  5. Installeer uv in de terminal.
  6. Open de activeringsmail, open de PDF met het wachtwoord uit het portaal en houd de tenantnaam en de sleutel bij de hand.
  7. Voer uvx sportalliance-mcp setup uit en volg de vragen van de wizard.
  8. Start je AI-app opnieuw en test hem met een simpele vraag.

Wat de connector kan

De connector koppelt een AI-assistent aan Magicline of PerfectGym Next. Je stelt je vraag in gewone taal, de connector zet die om in gecontroleerde en rechten-gestuurde acties en geeft je het antwoord terug. Je hoeft niet te programmeren.

Ondersteund worden Claude Desktop, Claude Code, Cursor, Windsurf, Gemini CLI en Antigravity.

Zo zien typische verzoeken eruit:

  • "Boek Jonas Weber in voor de Spinning-les van vanavond."
  • "Check Anna Schmidt in."
  • "Zet het contract van Anna in augustus op pauze, vakantie."
  • "Welke lessen zijn er morgen, en welke hebben nog vrije plekken?"
  • "Welke lidmaatschapsaanbiedingen verkopen we, en wat zou Premium kosten voor klant 10023?"

Eén installatie kan beide platformen gelijktijdig bedienen. Verschillende studio's en accounts draaien naast elkaar, elk met een eigen sleutel en eigen rechten.

De connector geldt voor Magicline en PerfectGym Next. Hij werkt niet met het klassieke PerfectGym-product op perfectgym.pl, dat een ander systeem is.

Vereisten

  • Een van de hierboven genoemde AI-apps
  • Een terminalvenster: de Terminal-app op Mac, PowerShell op Windows
  • Een mailbox die je kunt raadplegen, want de toegangssleutel komt per email
  • Ongeveer 30 minuten, eenmalig

Alle stappen in de delen A tot en met C gebeuren in een sandbox, een aparte testomgeving zonder live data. Alleen deel D brengt je naar live gebruik.

Rechten en beveiligingen

De connector werkt met drie toegangsniveaus. Hij start altijd op niveau 1, hogere niveaus moet je zelf bewust inschakelen.

  1. Alleen lezen (standaard, altijd actief): lesroosters, vrije plekken, lidmaatschapsaanbiedingen en studio-informatie. Geen ledengegevens, en niets kan worden gewijzigd.
  2. Ledengegevens (optioneel): profielen, contracten, saldi en check-inhistorie. Dit zijn echte persoonsgegevens van echte leden, schakel dit niveau dus alleen in als je klaar bent voor die verantwoordelijkheid.
  3. Wijzigingen aanbrengen (optioneel): lessen boeken, leden inchecken, prospects aanmaken, contracten op pauze zetten. Dit zijn echte acties in je studio, en de assistent laat je altijd eerst zien wat hij van plan is.

Vier beveiligingen staan altijd aan, welk niveau je ook kiest:

  • Belangrijke acties, zoals een contract opzeggen, een lidmaatschap afsluiten of financiële gegevens exporteren, worden nooit automatisch doorgevoerd. Een persoon bevestigt elke afzonderlijke actie.
  • Elk antwoord noemt de studio waar het vandaan komt, met een duidelijk PRODUCTION- of Sandbox-label.
  • De identiteit wordt bij elke start opnieuw gecontroleerd. Klopt er iets niet, dan start de connector liever niet dan te gokken.
  • Je sleutel leeft in de eigen kluis van je computer, dus in de macOS Keychain of de Windows Credential Manager, nooit in een platte tekstbestand.

Als een toegangssleutel per ongeluk is gedeeld, bijvoorbeeld in een chat, een screenshot of een ticket, geef hem dan opnieuw uit in het portaal.

Deel A: De applicatie aanmaken in het developerportaal

Deel A speelt zich volledig af in het developerportaal, op developer.sportalliance.com.

  1. Registreer je op developer.sportalliance.com, met email en wachtwoord of met Google. Heb je nog geen account, dan vind je Register here onder de inlogknop.

Inlogpagina van het developerportaal met de link Register here onder de inlogknop

  1. Bij je eerste keer inloggen bepaal je tot welke organisatie je behoort. Heeft je bedrijf al een partneraccount, vraag dan de beheerder om toegang. Kies anders Create New Partner Account, vul de partnernaam en bedrijfsnaam in, accepteer de voorwaarden en sla op met Save.

Welkomstscherm bij de eerste keer inloggen met de optie Create New Partner Account

Formulier voor de partnernaam, de bedrijfsnaam en het vakje voor de voorwaarden

  1. Kies het juiste merk in de merkkeuzelijst hierboven, Magicline of PerfectGym. Open dan Sandbox / Details en klik op Request Sandbox Credentials. Na 2 tot 3 minuten staat je eigen teststudio klaar, volledig gescheiden van live data.

Sandboxdetails vóór de provisioning, één klik start deze

  1. Open Sandbox / Applications en klik op Add New Application.

Overzicht Sandbox Applications met de knop Add New Application

  1. Kies in het dialoogvenster het applicatietype Generic, geef een naam op, bijvoorbeeld "MCP", en vul het activerings-emailadres in. Naar dat adres gaat later de activeringsmail met de tenantnaam en de toegangssleutel. De sleutel zit in een met een wachtwoord beveiligde PDF, en dat wachtwoord vind je in het portaal.

Dialoogvenster voor het aanmaken van een applicatie met type Generic, een naam en het activerings-emailadres

  1. Open de nieuwe applicatie, ga naar het tabblad Scopes en klik op Add Scopes. Scopes komen in paren als _READ en _WRITE per gebied, bijvoorbeeld voor afspraken, check-in, lessen en klantgegevens. Select All is handig voor de sandbox, voor live gebruik ken je ze beter bewust toe.

Een net aangemaakte applicatie zonder toegewezen scopes en dus zonder toegang

Scope-selectie met READ- en WRITE-paren per gebied

De scopes die je hier kiest, zijn de absolute buitengrens van wat de connector ooit kan bereiken, ongeacht wat je de assistent vraagt. Ken ze spaarzaam toe, later kun je altijd meer toevoegen.

Deel B: De integratie activeren in de studio

  1. Op Sandbox / Details staan nu je inloggegevens klaar: het webadres (https://<tenant>.web.sandbox.magicline.com voor Magicline, https://<tenant>.web.sandbox.perfectgym.com voor PerfectGym Next), de gebruikersnaam adminuser, het wachtwoord, dat je zichtbaar maakt met het oogicoon, en de basis-URL (https://<tenant>.open-api.sandbox.magicline.com respectievelijk https://<tenant>.open-api.sandbox.perfectgym.com). Log in met die gebruikersnaam en dat wachtwoord.

Sandboxdetails met inloggegevens zodra de provisioning is afgerond

  1. Ga in de studio naar Settings / Integrations / Overview. Je eigen applicatie verschijnt daar naast de ingebouwde partners. Klik op Activate in de betreffende rij.

Integratieoverzicht in de studio met je eigen applicatie en de knop Activate

Het activeringsdialoogvenster vraagt welke klantgegevens de studio deelt met de integratie, in twee groepen: bestaande klanten (leden, prospects, oud-leden) en nieuwe klanten (nieuwe leden, nieuwe prospects), vijf vakjes in totaal. Standaard staat alles uit. Zet alle vijf vakjes aan en klik pas daarna op Activate, anders ziet de connector een lege studio. Daarna ontvang je de activeringsmail met de tenantnaam en de sleutel.

Toestemmingsstap van de activering met de vakjes voor het delen van gegevens

Deel C: De connector instellen in de terminal

  1. Installeer uv. Deze brengt een eigen Python-omgeving mee, meer heb je niet nodig.
    • macOS en 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. Open de activeringsmail en daarin de PDF met het wachtwoord uit het portaal. Houd de tenantnaam en de sleutel bij de hand.
  3. Voer uvx sportalliance-mcp setup uit. De wizard vraagt eerst naar het platform en biedt Magicline en PerfectGym Next als opties aan.
  4. Vul de tenantnaam in en kies de omgeving: Sandbox voor de teststudio uit deel B, Production voor live gebruik. Elke optie laat je het volledig herleide API-adres zien, zodat je het kunt controleren. Plak daarna de sleutel uit de PDF, de invoer blijft daarbij verborgen. De wizard controleert de sleutel live tegen de API en laat zien welke studio hij daadwerkelijk opent. De server start standaard in de veilige alleen-lezenmodus, en de sleutel wordt opgeslagen in de sleutelketen van je besturingssysteem.
  5. Daarna volgt de optionele vraag over een koppeling met een datawarehouse. Dit is een geavanceerde functie voor enterprise-klanten met eigen datawarehouse-toegang, en de technische documentatie behandelt de details. Zonder die toegang sla je de vraag over met Enter, en verandert er niets anders.
  6. Kies tot slot de AI-apps die je wilt instellen. Al gedetecteerde apps staan voorgeselecteerd, en je bevestigt met Enter. Voor Claude Code is er nog een vraag over hoeveel je vooraf wilt goedkeuren. De aanbevolen keuze is: niet-persoonlijke leestools draaien zonder te vragen, terwijl ledengegevens en wijzigingen nog steeds eerst vragen.

De installatie is dan klaar. Start je AI-app opnieuw en de tools zijn beschikbaar.

De installatie testen

Start je AI-app opnieuw en stel een simpele vraag, bijvoorbeeld "Welke lessen staan er morgen op het rooster?". Komt er een antwoord terug uit je studio, dan reageren de tools zoals bedoeld.

Deel D: Overstappen naar live gebruik

Zodra de sandbox werkt zoals je wilt, herhaal je dezelfde stappen voor Application, Details en Scopes in het tabblad Production van het portaal en dien je de applicatie in voor beoordeling.

Wees hier extra voorzichtig met de scopes: wat je toekent, geldt voor elke studio die de integratie activeert.

Na goedkeuring door Sport Alliance kunnen live studio's de integratie precies zo activeren als in stap 8. De activering levert opnieuw een sleutel op in een met een wachtwoord beveiligde PDF. Voer daarna opnieuw uvx sportalliance-mcp setup uit, deze keer met de productietenant en de productiesleutel, en kies Production als omgeving.

De connector in het dagelijks gebruik

Aan de balie:

  • "Boek Jonas Weber in voor de Spinning-les van vanavond."
  • "Check Anna Schmidt in."
  • "Wanneer kan Anna haar contract op zijn laatst opzeggen?"
  • "Wat is haar saldo, en wat moet ze als volgende betalen?"
  • "Verleng haar pauze met een maand, wat zou dat kosten?"
  • "Maak een prospect aan voor Max Mustermann, max@example.com, en boek hem morgenochtend een gratis proefles."

Op de backoffice:

  • "Hoe druk is de studio op dit moment?"
  • "Welke lessen zijn er morgen, en welke hebben nog vrije plekken?"
  • "Laat het saldo en de komende kosten zien voor klant 10023."
  • "Noteer dat telefoontje bij zijn gegevens."

Vóór elke boeking of contractwijziging controleert de assistent automatisch of de actie voor dat lid überhaupt mogelijk is. Beperkte lessen, lidmaatschapsregels en pauzelimieten worden automatisch gerespecteerd.

Als een les of aanbod "niet bestaat", is dat meestal omdat het nog niet is aangemaakt in de backoffice. De connector kan de bestaande voorraad lezen en boeken, nieuwe lessen en aanbiedingen aanmaken blijft een backofficetaak.

Rechten later aanpassen

Het commando uvx sportalliance-mcp permissions is genoeg om toegangsniveaus aan of uit te zetten, of om afzonderlijke functies uit te schakelen, bijvoorbeeld lesboekingen behouden maar contractopzegging volledig uitsluiten. Je hoeft de installatie hiervoor niet opnieuw te doorlopen.

Start je AI-app opnieuw na elke wijziging van de instellingen.

Veelvoorkomende meldingen en wat ze betekenen

  • "The tenant does not exist on this host": sandbox- en live studio's staan op verschillende adressen. Je studio bestaat, alleen in de andere omgeving. De installatiewizard biedt je de wissel met één druk op de knop.
  • "The key is valid, but the integration has no scope…": de sleutel werkt, maar de applicatie heeft nooit rechten gekregen in het portaal. Ga terug naar stap 6, voeg de nodige scopes toe en probeer het opnieuw.
  • "The API rejected the key (401/403)": tenant en sleutel horen niet bij elkaar. Beide komen uit dezelfde activeringsmail, controleer ze daar opnieuw. Gebruik je beide platformen, zorg er dan voor dat de sleutel niet van het andere platform komt.
  • De verbinding start helemaal niet en meldt "STOPPING": de sleutel opent een andere studio dan waarvoor deze verbinding is ingesteld. Dat is de identiteitscontrole die precies doet wat ze moet doen. Doorloop de installatiewizard voor dat platform opnieuw.
  • Tools ontbreken in de AI-app: functies voor ledengegevens en wijzigingen verschijnen alleen als hun niveau is ingeschakeld. Controleer de rechten en start daarna de AI-app opnieuw.
  • De gegevens van een lid komen terug als "permission denied": sommige leden verzetten zich tegen het delen van hun gegevens met derden. Dat is hun recht, het platform respecteert dat, en de connector meldt dit in plaats van het opnieuw te proberen.

Meer studio's of platformen koppelen

Wil je extra studio's of het andere platform koppelen, doorloop dan gewoon opnieuw de installatie. Beide draaien dan naast elkaar in dezelfde AI-app, onderscheiden door kleur.

Let op: Dit artikel is met behulp van AI gemaakt en automatisch vertaald zonder redactionele controle. Onze excuses voor eventuele fouten.