Skip to main content

Set up and use the Sport Alliance MCP

Updated

In this article you will learn …

  • what the connector can do and which AI apps support it
  • how to set it up step by step in a sandbox
  • which permission tiers exist and how you control them
  • how to move from the sandbox test to live operation
  • what the most common messages mean

Contents

Quick Guide

  1. Register at developer.sportalliance.com and create a partner account.
  2. Choose your brand, request sandbox credentials and wait 2 to 3 minutes.
  3. Create an application and assign it the scopes you need.
  4. Activate the integration in the sandbox studio and enable all consent checkboxes.
  5. Install uv in the terminal.
  6. Open the activation email, open the PDF with the password from the portal, keep the tenant name and key at hand.
  7. Run uvx sportalliance-mcp setup and follow the wizard's questions.
  8. Restart your AI app and test it with a simple question.

What the connector can do

The connector links an AI assistant to Magicline or PerfectGym Next. You ask in plain language, the connector turns your request into checked and permission-gated actions and returns the answer. You do not need to write any code.

Supported apps are Claude Desktop, Claude Code, Cursor, Windsurf, Gemini CLI and Antigravity.

Typical requests look like this:

  • “Book Jonas Weber into tonight's Spin class.”
  • “Check Anna Schmidt in.”
  • “Pause Anna's contract for August, vacation.”
  • “What classes run tomorrow, and which still have free spots?”
  • “What membership offers do we sell, and what would Premium cost customer 10023?”

A single installation can serve both platforms at once. Different studios and accounts run side by side, each with its own key and its own permissions.

The connector applies to Magicline and PerfectGym Next. It does not work with the classic PerfectGym product at perfectgym.pl, which is a different system.

Prerequisites

  • One of the AI apps listed above
  • A terminal window: the Terminal app on Mac, PowerShell on Windows
  • An email inbox you can read, because the access key arrives by mail
  • About 30 minutes, one time

Every step in Parts A to C happens in a sandbox, which is a dedicated test environment with no live data. Only Part D moves you to live operation.

Permissions and safeguards

The connector works with three access tiers. It always starts at tier 1, and you have to switch on higher tiers deliberately.

  1. Read only (default, always active): class schedules, free spots, membership offers and studio information. No member data, and nothing can be changed.
  2. Member data (opt-in): profiles, contracts, balances and check-in history. This is real personal data of real members, so only switch the tier on when you are ready for that responsibility.
  3. Making changes (opt-in): booking classes, checking members in, creating leads, pausing contracts. These are real actions in your studio, and the assistant always shows you what it is about to do first.

Four safeguards are always active, whichever tier you choose:

  • Serious actions such as cancelling a contract, signing a membership or exporting financial data are never waved through automatically. A person confirms every single one.
  • Every answer names the studio it came from, with a clear PRODUCTION or Sandbox label.
  • The identity is re-checked on every start. If anything does not match, the connector refuses to start rather than guess.
  • Your key lives in your computer's own vault, which is the macOS Keychain or the Windows Credential Manager, never in a plain text file.

If an access key was shared by accident, for example in a chat, a screenshot or a ticket, reissue it in the portal.

Part A: Create the application in the developer portal

Part A happens entirely in the developer portal at developer.sportalliance.com.

  1. Register at developer.sportalliance.com, either with email and password or with Google. If you do not have an account yet, you will find Register here below the login button.

Developer portal login page with the Register here link below the login button

  1. On your first login you decide which organisation you belong to. If your company already has a partner account, ask its administrator for access. Otherwise choose Create New Partner Account, enter a partner name and company name, accept the terms and conditions and save with Save.

Welcome screen on first login with the Create New Partner Account option

Form for partner name, company name and the terms and conditions checkbox

  1. Choose the matching brand in the brand dropdown at the top, so either Magicline or PerfectGym. Then open Sandbox / Details and click Request Sandbox Credentials. After 2 to 3 minutes your own test studio is ready, completely separate from live data.

Sandbox details before provisioning, one click starts it

  1. Open Sandbox / Applications and click Add New Application.

Sandbox applications overview with the Add New Application button

  1. In the dialog, choose the application type Generic, enter a name, for example “MCP”, and enter the activation email address. That address later receives the activation email with the tenant name and access key. The key sits inside a password-protected PDF, and you will find the password for it in the portal.

Dialog for creating an application with type Generic, a name and the activation email address

  1. Open the new application, switch to the Scopes tab and click Add Scopes. Scopes come in pairs as _READ and _WRITE per domain, for example for appointments, check-in, classes and customer data. Select All is convenient for the sandbox, but for live operation it is better to grant them deliberately.

A fresh application with no scopes assigned and therefore no access

Scope selection with READ and WRITE pairs per domain

The scopes you choose here are the absolute outer limit of what the connector can ever reach, no matter what you ask the assistant. Grant them sparingly, you can always add more later.

Part B: Activate the integration in the studio

  1. Your credentials are now ready on Sandbox / Details: the web address (https://<tenant>.web.sandbox.magicline.com for Magicline, https://<tenant>.web.sandbox.perfectgym.com for PerfectGym Next), the username adminuser, the password, which you reveal with the eye icon, and the base URL (https://<tenant>.open-api.sandbox.magicline.com or https://<tenant>.open-api.sandbox.perfectgym.com respectively). Log in with that username and password.

Sandbox details with credentials after provisioning has finished

  1. In the studio, go to Settings / Integrations / Overview. Your own application appears there next to the built-in partners. Click Activate in its row.

Integrations overview in the studio with your own application and the Activate button

The activation dialog asks which customer data the studio shares with the integration, in two groups: existing customers (members, prospects, former members) and new customers (new members, new prospects), five checkboxes in total. Everything is off by default. Enable all five checkboxes and only then click Activate, otherwise the connector will see an empty studio. After that you receive the activation email with the tenant name and key.

Consent step of the activation with the data sharing checkboxes

Part C: Set up the connector in the terminal

  1. Install uv. It brings its own Python environment, and you do not need anything else.
    • macOS and 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 the activation email and the PDF inside it with the password from the portal. Keep the tenant name and key at hand.
  3. Run uvx sportalliance-mcp setup. The wizard first asks for the platform and offers Magicline and PerfectGym Next as the options.
  4. Enter the tenant name and choose the environment: Sandbox for the test studio from Part B, Production for live operation. Each option shows you the fully resolved API address so you can check it. Then paste the key from the PDF, where the input stays hidden. The wizard validates the key live against the API and shows you which studio it actually opens. The server starts in safe read-only mode by default, and the key is stored in your operating system's keychain.
  5. Next comes the optional question about a data warehouse connection. This is an advanced feature for enterprise customers with their own data warehouse access, and the technical documentation covers the details. Without that access, skip the question with enter, and nothing else changes.
  6. Finally, choose the AI apps you want to set up. Apps that were already detected are pre-selected, and you confirm with enter. For Claude Code there is one more question about how much to pre-approve. The recommended choice is: non-personal read tools run without asking, while member data and changes still ask first.

The setup is then done. Restart your AI app and the tools are available.

Test the setup

Restart your AI app and ask something simple, for example “What classes are on tomorrow's schedule?”. If an answer comes back from your studio, the tools respond as intended.

Part D: Move to live operation

Once the sandbox works the way you want, repeat the same steps for Application, Details and Scopes in the portal's Production tab and submit the application for review.

Be extra careful with the scopes here: whatever you grant applies to every studio that activates the integration.

After Sport Alliance approves it, live studios can activate the integration exactly as in step 8. Activation again delivers a key in a password-protected PDF. Then run uvx sportalliance-mcp setup again, this time with the production tenant and the production key, and choose Production as the environment.

The connector in everyday use

At the front desk:

  • “Book Jonas Weber into tonight's Spin class.”
  • “Check Anna Schmidt in.”
  • “When can Anna cancel her contract at the latest?”
  • “What's her balance, and what is she due to pay next?”
  • “Extend her freeze by a month, what would it cost?”
  • “Create a lead for Max Mustermann, max@example.com, and book him a free trial session for tomorrow morning.”

In the back office:

  • “How busy is the gym right now?”
  • “What classes are running tomorrow, and which still have free spots?”
  • “Show the account balance and upcoming charges for customer 10023.”
  • “Log that phone call on their record.”

Before any booking and any contract change, the assistant automatically checks whether the action is possible for that member at all. Restricted classes, membership rules and freeze limits are respected automatically.

If a class or an offer “does not exist”, it usually just has not been created in the back office yet. The connector can read and book existing inventory, while creating new classes and offers stays a back-office task.

Change permissions later

The command uvx sportalliance-mcp permissions is enough to switch access tiers on or off, or to disable individual abilities, for example to keep class booking but rule out contract cancellation entirely. You do not need to run through the setup again for this.

Restart your AI app after any change to the settings.

Common messages and what they mean

  • “The tenant does not exist on this host”: sandbox and live studios sit at different addresses. Your studio exists, just in the other environment. The setup wizard offers you the switch with one keystroke.
  • “The key is valid, but the integration has no scope…”: the key works, but the application was never granted any permissions in the portal. Go back to step 6, add the scopes you need and try again.
  • “The API rejected the key (401/403)”: tenant and key do not belong together. Both come from the same activation email, so check them there again. If you use both platforms, make sure the key is not from the other one.
  • The connection does not start at all and reports “STOPPING”: the key opens a different studio than the one this connection was set up for. That is the identity check doing exactly what it is meant to do. Run the setup wizard for that platform again.
  • Tools are missing in the AI app: abilities for member data and changes only appear when their tier is switched on. Check the permissions and then restart the AI app.
  • A member's data comes back as “permission denied”: some members object to their data being shared with third parties. That is their right, the platform honours it, and the connector reports it rather than retrying.

Connect more studios or platforms

If you want to connect additional studios or the other platform, simply run the setup again. Both then run side by side in the same AI app and are distinguished by colour.

Note: This article was created with the help of artificial intelligence and editorially reviewed.