Look, don't touch
Schedules, free class spots, membership offers, studio info. No member data, and nothing can be changed. This is the safe starting point.
Sport Alliance MCP · the complete guide
Run your studio by asking for it
One connector links your AI assistant to Magicline or PerfectGym Next. Ask questions and give instructions in plain language — no dashboards, no code. This guide has everything in one place: what it is, how it stays safe, the full illustrated set-up, and what day-to-day use looks like.
What is the Sport Alliance MCP?
It's a small connector that lets an AI assistant — such as Claude — talk to your studio platform on your behalf. You ask in everyday language; the connector turns the request into safe, permission-checked actions in Magicline or PerfectGym Next and brings the answer back. Nobody needs to write code or learn the system's menus. Once it's set up, the front desk can simply ask:
- 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?
It works with every common AI app: Claude Desktop, Claude Code, Cursor, Windsurf, Gemini CLI and Antigravity. One installation serves both platforms — a group can connect a Magicline studio and a PerfectGym Next club side by side in the same assistant, each with its own key and its own permissions.
Which product is this for? Magicline, and PerfectGym Next — Sport Alliance's current platform. It does not work with the classic PerfectGym product (perfectgym.pl), which uses a different system.
What it's allowed to do — you decide
Access comes in three levels. The connector starts at the first one and never moves up unless you switch the others on:
Member data
Profiles, contracts, balances, check-in history. Real personal data of real members — switch it on only when you're ready for that responsibility.
Making changes
Booking classes, checking members in, creating leads, pausing contracts. Real actions in your studio — the assistant always shows you what it's about to do.
And four protections that are always on, whatever you enable:
- Serious actions always ask first. Cancelling a contract, signing a membership or exporting financial data is never waved through automatically — a person confirms every single one.
- Every answer names the studio it came from. Bookings and contract actions carry the studio's name and a clear PRODUCTION or sandbox label, so nothing lands in the wrong place unnoticed.
- The identity is re-checked on every start. The connector confirms the key still opens the studio it was set up for — if anything was swapped around, it refuses to start rather than guess.
- Your key lives in the computer's own vault (macOS Keychain / Windows Credential Manager) — never in a plain text file.
Setting it up — before you start
The set-up below takes roughly half an hour and you only do it once. You'll need three things: an AI app from the list above, a terminal window — that's the Terminal app on a Mac or PowerShell on Windows, used only to paste the two commands this guide gives you — and an email inbox you can read, because your access key arrives by mail.
Two things worth knowing before you begin:
- Everything in Parts A–C happens in a sandbox — a dedicated practice studio with no live data. Try things there until you're confident, then go live in Part D.
- The scopes you pick in step 6 are the outer limit of what the connector can ever reach — grant the least you need; you can always add more later.
Part A · Developer portal
Register, define your application, set its scopes
All of Part A happens at developer.sportalliance.com, under the Sandbox tab.
Create your developer account
Go to developer.sportalliance.com and register — either with an email and password or by continuing with Google.
Create a partner account
On first login the portal offers two paths. If your company already has a partner account, ask its administrator to add you. Otherwise choose Create New Partner Account.
Give the partner a name, add your company name, accept the terms and conditions, and save.
Request a sandbox environment
Pick your brand (Magicline or PerfectGym) in the dropdown at the top, then open Sandbox → Details and click Request Sandbox Credentials. Provisioning takes two to three minutes and gives you a dedicated test studio that is completely separate from any live data.
Add a developer application
Open Sandbox → Applications and click Add New Application. The application is what the studio will later see and activate as an integration.
Fill in the application details
In the dialog, set:
- Developer Application Type —
Generic - Application Name — whatever the studio should see, e.g.
MCP - Activation Email — the address that receives the activation mail when a studio switches the integration on. That mail carries the tenant name and the API key — the key arrives inside a password-protected PDF, and the password to open it is shown in the developer portal. Use an inbox you can read.
Add scopes — this is the permission boundary
Select your application, open its Scopes tab, and click Add Scopes.
Scopes decide what the MCP can do
The scopes you grant here are exactly what the MCP server will be able to read and write through its tools — nothing outside them is reachable, whatever an assistant asks for. If you want system-level control over the MCP's abilities (say, read-only access, or no finance endpoints), this screen is where you enforce it. Select All is convenient for sandbox testing; for production, grant deliberately.
Part B · Sandbox studio
Log in to the sandbox and activate the integration
Part B happens inside your sandbox studio's own web interface — Magicline in the screenshots below.
Open your sandbox
Back on Sandbox → Details, the provisioned environment now shows everything you need to get in:
- Web
- https://<tenant>.web.sandbox.magicline.com
- Username
- adminuser
- Password
- revealed with the eye icon
- Base-URL
- https://<tenant>.open-api.sandbox.magicline.com
Open the Web URL and log in with that username and password. The Base-URL is the API host the MCP server will talk to.
Activate the integration in the studio
Inside the sandbox studio, go to Settings → Integrations → Overview, find your application in the partner list, and click Activate.
The activation dialog asks which customer data the studio shares with the integration, in two groups: existing customers (members, prospects and former members) and new customers (new members and new prospects) — five checkboxes in total. Everything is off by default. Tick all of the sharing options before clicking Activate, otherwise the MCP will see an empty studio.
What happens next: the activation email arrives at the address from step 5, carrying the tenant name and the API key in a password-protected PDF. Continue with Part C to unlock the key and wire the MCP into your AI clients.
Part C · Terminal
Install the MCP server and run the setup wizard
Part C happens in your terminal. One command does the whole configuration — the captures below show the full wizard run.
Install uv
The server runs via uv, which installs its own Python — nothing else is needed on the machine.
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Unlock your API key
Activating the integration (step 8) sent an activation email to the address from step 5. The email names your tenant, and the API key is inside a password-protected PDF attached to it. The password to open that PDF is shown in the developer portal — open the PDF with it and keep the tenant name and key at hand for the next step.
Which value is which: the tenant is the first part of the Base-URL from step 7 — for https://mcp.open-api.sandbox.magicline.com the tenant is mcp. The key is the long string from the PDF.
Run the setup wizard
uvx sportalliance-mcp setupThe first question is your platform. Pick Magicline or PerfectGym Next — if you're unsure, the last menu entry explains how to tell them apart from the hostname in your activation email.
╭─────────────────────────────────────────────────────────────────────╮ │ │ │ ───────────────────────────────────────────────────────────── │ │ │ │ ███████╗██████╗ ██████╗ ██████╗ ████████╗ │ │ ██╔════╝██╔══██╗██╔═══██╗██╔══██╗╚══██╔══╝ │ │ ███████╗██████╔╝██║ ██║██████╔╝ ██║ │ │ ╚════██║██╔═══╝ ██║ ██║██╔══██╗ ██║ │ │ ███████║██║ ╚██████╔╝██║ ██║ ██║ │ │ ╚══════╝╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ │ │ █████╗ ██╗ ██╗ ██╗ █████╗ ███╗ ██╗ ██████╗███████╗ │ │ ██╔══██╗██║ ██║ ██║██╔══██╗████╗ ██║██╔════╝██╔════╝ │ │ ███████║██║ ██║ ██║███████║██╔██╗ ██║██║ █████╗ │ │ ██╔══██║██║ ██║ ██║██╔══██║██║╚██╗██║██║ ██╔══╝ │ │ ██║ ██║███████╗███████╗██║██║ ██║██║ ╚████║╚██████╗███████╗ │ │ ╚═╝ ╚═╝╚══════╝╚══════╝╚═╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝╚══════╝ │ │ │ │ Sport Alliance MCP v0.2.1 │ │ │ │ One install, every platform: │ │ Magicline <tenant>.open-api.magicline.com │ │ PerfectGym Next <tenant>.open-api.perfectgym.com │ │ │ │ Read-only by default — member data and writes are opt-in. │ │ │ │ Documentation: developer.sportalliance.com │ │ ───────────────────────────────────────────────────────────── │ │ │ ╰─────────────────────────────────────────────────────────────────────╯ ? Which platform is this studio on? (↑/↓, enter) » Magicline <tenant>.open-api.magicline.com PerfectGym Next <tenant>.open-api.perfectgym.com --------------- I'm not sure — help me tell them apart
Enter tenant, environment and API key
Type the tenant name, then choose the environment — pick Sandbox for the studio from Part B. Each option shows the fully resolved API host, so a key can't silently land on the wrong environment.
▌ API Key Configuration ───────────────────────────── You need the tenant name and API key from your Magicline activation email. The base URL looks like https://<tenant>.open-api.magicline.com ? Tenant name: mcp ? Is this a production or sandbox studio? (Use arrow keys) » Production (https://mcp.open-api.magicline.com) Sandbox (https://mcp.open-api.sandbox.magicline.com) Custom URL
Paste the API key from the PDF at the key prompt (input is hidden). The wizard validates it against the live API and shows the studio the key actually opens — Studio-1 for a fresh sandbox. By default the server starts in safe read-only mode; the key is stored in the OS key store (macOS Keychain / Windows Credential Manager), never in a plain-text file.
? API key for mcp.open-api.sandbox.magicline.com: Validating against the live API ... ✓ Connected successfully — Studio-1 (this is the studio the key actually opens — it is stored and re-checked every time the server starts) ▌ Tool Permissions ──────────────────────── ✓ Safe read-only mode — no member data, no writes. To enable elevated capabilities, re-run with setup --advanced, or use sportalliance-mcp permissions any time. ▌ Key Storage ─────────────────── ✓ API key stored in the macOS Keychain.
Optional — connect the data warehouse
If your organisation has the enterprise data warehouse service (Amazon Redshift), answer y here to unlock the SQL analytics tools. Enter the cluster host, port (5439 is the default), database, user and password — the password goes into the system keyring, alongside the API key. No warehouse? Press enter to skip; nothing else changes.
▌ Data Warehouse (optional) ───────────────────────────────── ? Configure a Redshift data warehouse connection? [y/n] (n): y Use a warehouse user with read-only grants — the server opens read-only transactions but cannot enforce them against arbitrary SQL. ? Warehouse host: examplecluster.abc123xyz789.eu-central-1.redshift.amazonaws.com ? Warehouse port (5439): ? Warehouse database: dwh ? Warehouse user: mcp_readonly ? Warehouse password: ✓ Warehouse password stored in the system keyring.
Choose your AI clients and finish
The wizard lists the supported AI clients and pre-selects the ones it detects on your
machine. Confirm with enter — Claude Code is configured via
claude mcp add --scope user automatically; the others get the server written
into their own config files.
▌ MCP Clients ─────────────────── ? Select the AI clients to configure (↑/↓ move, space to toggle, enter to confirm) » ○ Claude Desktop (not detected) ○ Cursor (not detected) ○ Windsurf (not detected) ○ Gemini CLI (not detected) ○ Antigravity (not detected) ● Claude Code
For Claude Code, one last choice: how much to pre-approve. The recommended option lets non-personal read tools run without a prompt while member data and writes still ask.
▌ Permission Prompts (Claude Code) ──────────────────────────────────────── ? Claude Code asks for approval before every tool call. Pre-approve Magicline tools? Pre-approve non -personal reads — member data and writes still ask (recommended) ✓ Pre-approved non-personal read-only Magicline tools in ~/.claude/settings.json ✓ Magicline configured. Restart your AI client and the Magicline tools will be available. Fine-tune tiers or disable individual tools any time with sportalliance-mcp permissions.
Validate the setup: restart your AI client and ask a simple question — "What classes are on tomorrow's schedule?" — to confirm the tools respond. From the terminal, uvx sportalliance-mcp test checks every configured studio against the live API and prints the studio name each key opens.
Part D · Production
Promote the application to production
Back at developer.sportalliance.com, under the Production tab.
Same steps, Production tab, then submit for review
Once the sandbox MCP behaves the way you want, repeat the application setup — application, details, scopes — under the portal's Production tab, and submit the application for review. Scopes deserve extra care here: what you grant is what every activating studio exposes.
After Sport Alliance approves the application, live studios can activate it exactly as
in step 8. Activation again delivers the key as a password-protected PDF; run
uvx sportalliance-mcp setup once more with the production tenant and key —
choosing Production this time in step 12 — and the MCP works against your live
Magicline or PerfectGym Next environment.
After set-up · Everyday use
A day at the front desk
Open your AI app and ask — that's the whole workflow.
At the desk, between members
- 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.
Good to know: before any booking or contract change, the assistant first checks the action is actually possible for that member — restricted classes, membership rules and freeze limits are respected automatically. And if a class or offer "doesn't exist", it usually means it hasn't been created in the back office yet — the connector can read and book your inventory, but creating classes and offers stays a back-office job.
After set-up · Managing it
Changing your mind later
Every command below is pasted into the same terminal as Part C — no set-up re-run needed.
The five commands that matter
uvx sportalliance-mcp permissionsSwitch access levels on or off, or disable individual abilities (say, keep class bookings but rule out contract cancellation entirely).
uvx sportalliance-mcp keys listSee every stored studio key, grouped by platform, with its environment and studio name.
uvx sportalliance-mcp keys addStore the key for another studio — or your other platform.
uvx sportalliance-mcp testCheck every configured studio against the live system and show which studio each key opens.
uvx sportalliance-mcp statusA quick health check of the configuration on this computer — finds mixed-up keys, mismatched settings and leftovers, without touching the network.
Second platform? Run uvx sportalliance-mcp setup again and pick the other platform — the wizard even offers this at the end of the first run. Both studios then live side by side in your AI app, each in its own colours.
If something doesn't work
The usual suspects, in plain language
Each of these is something the connector tells you on purpose — here's what it means.
What the messages mean
"The tenant does not exist on this host"
Practice (sandbox) studios and live studios live at different addresses. Your studio exists — just on the other environment. The set-up wizard offers 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 developer portal. Go back to step 6, add the scopes you need, and try again.
"The API rejected the key (401/403)"
Tenant and key don't belong together. Both come from the same activation email — re-check them there. If you run both platforms, make sure this key isn't from the other one; status spots exactly that mix-up.
The server refuses to start with a "STOPPING" message
The key opens a different studio than this connection was set up for — that's the identity check doing its job. Re-run the set-up wizard for that platform.
Tools are missing in the AI app
Member data and change-making abilities only appear when their level is switched on — check uvx sportalliance-mcp permissions, then restart the AI app. Restart it after any settings change.
A member's data comes back as "permission denied"
Some members opt out of third-party data access. That's their right, the platform is honouring it, and the connector reports it rather than retrying.
For your IT team — the technical corner
Everything above is also configurable by hand. The connector is the open-source Python package sportalliance-mcp; an AI client launches it on demand over stdio — there is no server to host. A client entry looks like this (the key is not in the file — it's resolved from the OS key store):
{ "mcpServers": { "PerfectGymNext": {
"command": "uvx", "args": ["sportalliance-mcp"],
"env": { "SPORTALLIANCE_PLATFORM": "perfectgym-next",
"SPORTALLIANCE_TENANT": "sport-alliance-de",
"SPORTALLIANCE_ENVIRONMENT": "sandbox",
"SPORTALLIANCE_TOOLS": "read" } } } }Full reference — every environment variable, headless/CI use, the optional Redshift data-warehouse tools, and per-tool deny-lists — lives in the package README on PyPI. Legacy magicline-mcp installations keep working unchanged; running the new set-up offers a one-time migration that copies keys forward and deletes nothing.
sport alliance mcp · technical reference
The lower-level detail
Everything the guide summarises, in full: the complete tool catalog straight from the running package, every command and variable, manual configuration, the data warehouse, and operating practices. Written for admins and IT.
Reference · Tools
Every tool, by permission tier
Generated from sportalliance-mcp v0.2.1 — identical on Magicline and PerfectGym Next. Tools marked always asks are excluded from every pre-approval list; a human confirms each call.
Read · 20 tools always available — no member data
get_additional_modulesGet the studio's additional modules (paid add-ons like drink flatrate, solarium) available in member self-service.
get_appointment_slotsGet available time slots for a bookable appointment type.
get_bookable_appointmentGet one bookable appointment type by its ID.
get_classGet a single class (group fitness course) by its ID.
get_class_slotGet one specific class slot with its current state (times, instructor, free capacity, booking windows).
get_contract_cancelation_reasonsGet the studio's configured contract cancelation reasons (needed to create a cancelation).
get_lead_configGet the studio's lead configuration: which fields are required or available when creating a lead.
get_membership_offerGet one membership offer with full details (terms, pricing, modules).
get_studio_informationGet general information about the studio: name, address, contact details, opening hours and configuration.
get_studio_utilizationGet the studio's current utilization (how busy the gym is right now).
get_trial_offer_appointment_slotsGet available slots for a trial-offer appointment type.
get_trial_offer_class_slotsGet bookable trial-offer slots for one class.
get_trial_offer_configGet a trial offer configuration by its ID.
list_additional_information_fieldsList the studio's configured additional information fields — the custom profile fields available on every customer (IDs, names, types and allowed values), e.g.
list_bookable_appointmentsList the studio's bookable appointment types (e.g.
list_class_slotsList upcoming bookable class slots (scheduled sessions) with start time, instructor and free capacity — across all classes, or for one class via class_id.
list_classesList the studio's active classes (group fitness courses) with title, description and schedule information.
list_membership_offersList all membership offers (tariffs/plans) the studio currently sells.
list_trial_offer_appointmentsList appointment types that can be booked as a trial offer.
list_trial_offer_classesList classes that can be booked as a trial offer.
Member data · 33 tools opt-in — personal data of members
get_account_transactionsGet a customer's past account transactions (charges with their open amounts).
get_appointment_bookingGet a single appointment booking by its booking ID.
get_appointment_bookingsGet a customer's appointment bookings within roughly +/- 2 weeks of today.
get_class_bookingGet a single class booking by its booking ID (including the customer).
get_class_bookingsGet all class bookings for a specific customer.
get_communication_preferencesGet a customer's communication preferences (which channels they accept per message category: CONTRACT, GENERAL, APPOINTMENT, NEWSLETTER, LOYALTY_PROGRAM).
get_contract_dataGet a customer's contract data as shown in member self-service, including cancelation options.
get_customerGet a customer's full profile by their ID.
get_customer_balanceGet a customer's account balance data (credits and open amounts).
get_customer_benefitsGet a customer's (partner integration) benefits, optionally filtered by benefit keys.
get_customer_benefits_byGet a customer's benefits by a member identifier (access card number, barcode or PIN) instead of their customer ID.
get_customer_byLook up a customer by a member identifier: club access card number, customer number, barcode, QR code UUID, PIN, or debtor ID.
get_customer_checkinsGet a customer's studio check-in history.
get_customer_contractGet one membership contract of a customer by contract ID.
get_customer_contractsGet a customer's membership contracts.
get_customer_transactionsGet a customer's transactions in a date range (YYYY-MM-DD, max 365 days).
get_debt_claim_previewPreview the future debt claims (upcoming dues) for one of the customer's contracts — e.g.
get_employeeGet a single employee by their ID.
get_idle_periodGet one idle period (pause/freeze/hold) by its ID — current state, dates and verification status.
get_idle_period_configGet the idle period (pause/freeze/hold) configuration of a contract: allowed reasons, durations and limits.
get_idle_periodsGet the idle periods (contract pauses/freezes/holds) of a contract.
get_membership_switch_configGet one membership switch configuration for a customer, including the destination offers, terms and modules available for that switch path.
get_membership_switch_configsGet the membership switch paths (upgrades/downgrades) available to a customer.
get_purchasable_additional_modulesGet the additional modules (add-ons) a specific contract could purchase.
get_remaining_idle_periodsGet how many idle-period (pause/freeze) free terms and max terms the contract has left.
get_tax_advisor_exportGet a tax advisor export by its ID (status and download information).
get_upcoming_transactionsGet a customer's upcoming account transactions within the next year (future dues and scheduled charges).
list_customersList customers.
list_employeesList the studio's employees (trainers and staff).
preview_add_membershipPreview adding a new contract to an existing customer without creating it — the authoritative price calculation including their discounts.
preview_membership_signupPreview a brand-new membership signup (price quote for a prospect) without creating anything.
preview_membership_switchPreview a membership switch (upgrade/downgrade) without performing it — the authoritative source for pro-rated costs and fees (paymentPreview.dueOnSigningAmount).
search_customersSearch customers by name (prefix match), email, date of birth (YYYY-MM-DD) or phone number (+49...
Writes · 34 tools opt-in — creates and changes things
add_membershipAssign a membership contract to an existing customer — a REAL, binding contract; confirm details with the user first. ALWAYS ASKS
add_to_communication_threadAdd a communication entry to an existing thread on a customer's record.
book_appointmentBook an appointment for a customer.
book_class_slotBook a class slot for a customer.
book_trial_appointmentBook a trial-offer appointment for a lead customer.
book_trial_classBook a trial-offer class slot for a lead customer (create the lead with create_trial_lead first).
cancel_appointment_bookingCancel an existing appointment booking by its booking ID.
cancel_class_bookingCancel an existing class booking by its booking ID.
cancel_contractCreate an ordinary contract cancelation for a customer. ALWAYS ASKS
check_in_customerCreate a manual studio check-in for a customer.
check_out_customerCreate a manual studio checkout for a customer.
confirm_trial_bookingConfirm a trial offer booking.
create_communication_threadLog a past communication/interaction on a customer's record as a new thread (e.g.
create_customerCreate a new customer (prospect — no contract).
create_idle_periodFreeze or pause a membership: create an idle period (hold) on a contract.
create_leadCreate a new lead (prospect).
create_tax_advisor_exportCreate a tax advisor export. ALWAYS ASKS
create_trial_leadCreate a lead customer for a trial offer — mandatory before booking a trial session; returns the customerId to book with.
preview_idle_period_updatePreview the charges/fees of changing an existing idle period (pause/freeze), without applying it — e.g.
set_additional_information_fieldsSet a customer's additional information field values (custom profile fields) — THE tool for putting notes on a customer's profile (e.g.
signup_membershipSign up a brand-new member: creates the customer AND a REAL, binding membership contract in one step — confirm details with the user first. ALWAYS ASKS
update_communication_preferencesUpdate a customer's communication preferences.
update_idle_periodChange an existing idle period / freeze (extend, shorten, move, or convert an unlimited freeze to a fixed end).
use_customer_benefitRecord a usage of a customer's benefit (consumes one unit of their contingent).
validate_additional_moduleCheck whether an additional module could be added to a contract, without purchasing it.
validate_appointment_bookingCheck whether an appointment can be booked for a customer without booking it — some appointments are restricted to certain memberships.
validate_class_bookingCheck whether a class slot can be booked for a customer, without booking it.
validate_idle_periodCheck whether an idle period (pause/freeze/hold) request is valid — catches overlaps, max-term violations and too-early start dates — without creating it.
validate_leadValidate lead data against the studio's lead config without creating it.
validate_trial_appointment_bookingCheck whether a trial-offer appointment can be booked for a lead customer, without booking it.
validate_trial_class_bookingCheck whether a trial class slot can be booked for a lead customer, without booking it.
validate_trial_leadValidate trial-lead data against the trial offer config without creating the lead — catches missing required fields and duplicate customers.
withdraw_contract_cancelationWithdraw (undo) an ordinary cancelation of a customer's contract. ALWAYS ASKS
withdraw_idle_periodWithdraw (cancel) a scheduled idle period / freeze that hasn't started yet.
Data warehouse · 6 tools appear only when a warehouse connection is configured
warehouse_describe_tableDescribe the columns of a warehouse table: column_name, data_type, is_nullable, and column_default.
warehouse_docsLook up data warehouse documentation by topic: business definitions, per-table analyst notes (correct filters, join keys, gotchas) and SQL rules.
warehouse_list_schemasList the queryable schemas in the data warehouse.
warehouse_list_tablesList tables and views in a warehouse schema.
warehouse_queryRun a read-only SQL query against the data warehouse.
warehouse_query_piiRun a read-only SQL query against the data warehouse with full, unmasked results including all string/varchar columns (PII).
Reference · Commands
Every command, one table
Prefix with uvx, or uv run inside the repo.
sportalliance-mcp setupOne-time interactive set-up — platform question first, safe read-only mode.
setup --platform <id>Skip the platform question: magicline or perfectgym-next (aliases perfectgym, pgnext).
setup --advancedOffer the member-data and write tiers plus the per-tool editor during set-up.
setup --auto-updateClients always launch the latest published version (sportalliance-mcp@latest).
setup --claude-codeAlso configure Claude Code via claude mcp add --scope user.
setup --allow-allPre-approve tools in Claude Code, writes included — destructive contract/finance actions still always ask.
testVerify every configured entry against the live API; prints the studio each key actually opens.
statusLocal config doctor — no network. Flags platform/host/environment disagreements, the same inline key under two platforms, stale env-var twins, dead launcher paths, missing keyring entries and orphaned allow rules.
toolsList every tool, grouped by permission tier.
permissions [--platform p]Change tiers or enable/disable individual tools; asks which platform when more than one is configured.
keys listStored keys grouped by platform — environment, studio label, masked key, active tenant.
keys addStore and validate a key for another studio; the key prompt shows the fully resolved host.
keys activate <p/tenant>Switch a platform's client entries to another studio (endpoint switches with it, only that platform's entries are touched). Bare tenants work when unambiguous.
keys delete <p/tenant>Remove a stored key from the OS keyring (both current and legacy service), with real per-service outcomes.
warehouse set|status|deleteManage the data-warehouse password in the OS keyring.
sportalliance-mcpRun the MCP server on stdio — your AI client does this for you.
Reference · Variables
Environment variables
Written by the wizard; set them yourself only in non-interactive environments (CI, Docker, headless Linux). MAGICLINE_* twins remain supported for existing Magicline configs — if both prefixes are set they must agree, or the server refuses to start.
SPORTALLIANCE_PLATFORMRequired. magicline or perfectgym-next. The server never guesses; a config carrying only MAGICLINE_* variables deterministically means Magicline (with a deprecation note).
SPORTALLIANCE_TENANTRequired. The studio's subdomain from the activation email.
SPORTALLIANCE_ENVIRONMENTproduction (default) or sandbox — explicit, never inferred. Sandbox and production are disjoint tenant namespaces.
SPORTALLIANCE_TOOLSEnabled tiers, comma-separated: read (always included), pii, write.
SPORTALLIANCE_TOOLS_EXCLUDEIndividual tools to disable, comma-separated — a deny-list, so newly added tools stay enabled by default. Managed by permissions.
SPORTALLIANCE_API_KEYInline key — overrides the OS keyring. Only for machines without one.
SPORTALLIANCE_BASE_URLCustom endpoint (HTTPS required; plain http only for localhost). Refused when the host belongs to a different platform than declared.
SPORTALLIANCE_MAX_RPSClient-side request ceiling, requests/second (default 3 — a deliberate small slice of the key's shared rate allowance). 0 disables the throttle.
WAREHOUSE_HOST / _PORT / _DATABASE / _USERRedshift endpoint of the enterprise data warehouse; warehouse tools register only when host, database and user are all present. Port defaults to 5439.
WAREHOUSE_PASSWORDOverrides the OS keyring — only needed where no keyring exists.
Reference · Manual configuration
Wiring a client by hand
The wizard edits these files for you; the format is identical everywhere.
Config file locations
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json)
Claude Coderegistered via claude mcp add --scope user; pre-approval rules live in ~/.claude/settings.json
Cursor~/.cursor/mcp.json
Windsurf~/.codeium/windsurf/mcp_config.json
Gemini CLI~/.gemini/settings.json (merged into the existing file)
Antigravity~/.gemini/antigravity/mcp_config.json
Two platforms from one install
{ "mcpServers": {
"Magicline": { "command": "uvx", "args": ["sportalliance-mcp"],
"env": { "SPORTALLIANCE_PLATFORM": "magicline",
"SPORTALLIANCE_TENANT": "acme-fitness",
"SPORTALLIANCE_ENVIRONMENT": "production",
"SPORTALLIANCE_TOOLS": "read" } },
"PerfectGymNext": { "command": "uvx", "args": ["sportalliance-mcp"],
"env": { "SPORTALLIANCE_PLATFORM": "perfectgym-next",
"SPORTALLIANCE_TENANT": "sport-alliance-de",
"SPORTALLIANCE_ENVIRONMENT": "sandbox",
"SPORTALLIANCE_TOOLS": "read" } } } }Server keys are exactly Magicline and PerfectGymNext — Claude Code permission rules embed them (mcp__Magicline__list_classes), so they never change. Keys are per studio: never paste the same key into two platform entries — status flags exactly that. Keys resolve from the OS keyring (service sportalliance-mcp, username platform:tenant); on keyring-less machines use SPORTALLIANCE_API_KEY inline. On Windows, prefer the full path to uvx.exe as the command — GUI apps don't always inherit PATH (the wizard does this automatically).
Reference · Data warehouse
SQL analytics, with guardrails
Optional — for operators with enterprise data warehouse access (Amazon Redshift, schema erp_v2). Docs: Magicline · PerfectGym Next.
How queries are contained
- Results capped at 500 rows (with a truncation flag), a 60-second statement timeout, multi-statement SQL rejected, and every query runs in a read-only transaction that is rolled back.
- At read tier, warehouse_query masks string and known personal-data columns as <withheld>; unmasked rows need the pii tier via warehouse_query_pii. The masking keys on result column names, so it is best-effort hygiene, not a security boundary — if you must guarantee no PII at read tier, disable warehouse_query or enforce masking in the warehouse itself.
- Connect with a read-only warehouse user. The database user's grants are the real enforcement — arbitrary SQL could escape anything softer.
- A group sharing one warehouse across both platforms stores the password once (keyring entry warehouse:user@host/database).
- The server teaches the AI the schema: a key-tables cheat sheet in the instructions, topic lookup via warehouse_docs (churn, revenue, KPI definitions, join keys, status filters), and the full glossary as MCP resources (magicline://warehouse/glossary / perfectgym-next://warehouse/glossary).
Reference · Best practices
Operating it responsibly
The judgement calls, spelled out.
Considerations before going live
- Writes are real. Enabling the write tier lets the assistant take real, potentially irreversible actions — cancelling member contracts included. Member data carries everything GDPR (and CCPA and local equivalents) implies. If you can't review each call before approving it, keep those tiers off — especially against production.
- Two permission layers, different jobs. Tiers (and per-tool disables) control which tools exist — the server never even registers what isn't enabled. Claude Code pre-approval only controls whether Claude asks before using tools that do exist. Read-only pre-approval on a read-only tier is safe; --allow-all with writes enabled means routine actions run unconfirmed — destructive ones still always ask, by design.
- Scopes are the outer boundary. Whatever the developer-portal application grants is the ceiling on everything above; grant the least you need. A valid key with no scopes fails with a message that says exactly that.
- Sandbox first. Sandbox and production are separate tenant namespaces with separate keys — rehearse in sandbox, promote deliberately (Part D of the guide).
- Rate limits are shared. Your API key's allowance is shared with the studio's other integrations; the client-side throttle (3 requests/second by default) keeps the MCP a good citizen. Raise it deliberately, not reflexively.
- Rotate keys that leak. A key pasted into a chat, a screenshot or a ticket is a shared credential — reissue it in the portal and run keys add again.
- Upgrading from magicline-mcp: running the new set-up offers a one-time migration — keys copied forward with verification, nothing deleted, the Magicline server key and existing allow rules untouched. Configs carried over by hand (a bare MAGICLINE_* env block) work with zero action. Staying on magicline-mcp 0.1.2 is also fine.
- Every start is verified. The server re-checks that the key still opens the studio it was configured for and refuses to start on a mismatch; results of risky tools carry the studio name and an explicit PRODUCTION/sandbox label.