Vai al contenuto principale

Configura e usa il Sport Alliance MCP

  • Aggiornato

In questo articolo imparerai …

  • cosa può fare il connettore e quali app di IA lo supportano
  • come configurarlo passo dopo passo in una sandbox
  • quali livelli di permessi esistono e come controllarli
  • come passare dal test in sandbox all'uso in produzione
  • cosa significano i messaggi più comuni

Contenuti

Guida rapida

  1. Registrati su developer.sportalliance.com e crea un account partner.
  2. Scegli il tuo brand, richiedi le credenziali sandbox e attendi 2-3 minuti.
  3. Crea un'applicazione e assegnale gli scope necessari.
  4. Attiva l'integrazione nello studio sandbox e seleziona tutte le caselle di consenso.
  5. Installa uv nel terminale.
  6. Apri l'email di attivazione, apri il PDF con la password dal portale e tieni a portata di mano il nome del tenant e la chiave.
  7. Esegui uvx sportalliance-mcp setup e segui le domande della procedura guidata.
  8. Riavvia la tua app di IA e provala con una domanda semplice.

Cosa può fare il connettore

Il connettore collega un assistente di IA a Magicline o PerfectGym Next. Formuli la tua richiesta in linguaggio comune, il connettore la trasforma in azioni verificate e controllate dai permessi, e ti restituisce la risposta. Non devi scrivere codice.

Sono supportati Claude Desktop, Claude Code, Cursor, Windsurf, Gemini CLI e Antigravity.

Ecco come si presentano le richieste tipiche:

  • «Prenota Jonas Weber al corso di Spin di stasera.»
  • «Registra l'ingresso di Anna Schmidt.»
  • «Metti in pausa il contratto di Anna per agosto, vacanze.»
  • «Quali corsi ci sono domani, e quali hanno ancora posti liberi?»
  • «Quali offerte di abbonamento vendiamo, e quanto costerebbe Premium per il cliente 10023?»

Una sola installazione può servire entrambe le piattaforme contemporaneamente. Studi e account diversi funzionano fianco a fianco, ciascuno con la propria chiave e i propri permessi.

Il connettore vale per Magicline e PerfectGym Next. Non funziona con il prodotto PerfectGym classico su perfectgym.pl, che è un sistema diverso.

Requisiti

  • Una delle app di IA elencate sopra
  • Una finestra di terminale: l'app Terminale su Mac, PowerShell su Windows
  • Una casella email che puoi consultare, perché la chiave di accesso arriva per email
  • Circa 30 minuti, una sola volta

Tutti i passaggi delle parti A-C si svolgono in una sandbox, un ambiente di test dedicato senza dati reali. Solo la parte D ti porta in produzione.

Permessi e misure di sicurezza

Il connettore lavora con tre livelli di accesso. Parte sempre dal livello 1, e devi attivare i livelli superiori in modo deliberato.

  1. Solo lettura (predefinito, sempre attivo): orari dei corsi, posti liberi, offerte di abbonamento e informazioni sullo studio. Nessun dato dei membri, e niente può essere modificato.
  2. Dati dei membri (opzionale): profili, contratti, saldi e storico dei check-in. Sono dati personali reali di membri reali, quindi attiva questo livello solo quando sei pronto per quella responsabilità.
  3. Effettuare modifiche (opzionale): prenotare corsi, registrare l'ingresso dei membri, creare contatti interessati, mettere in pausa i contratti. Sono azioni reali nel tuo studio, e l'assistente ti mostra sempre prima cosa sta per fare.

Quattro misure di sicurezza sono sempre attive, indipendentemente dal livello scelto:

  • Le azioni importanti, come annullare un contratto, firmare un abbonamento o esportare dati finanziari, non vengono mai approvate automaticamente. Una persona conferma ciascuna di esse.
  • Ogni risposta indica lo studio da cui proviene, con un'etichetta chiara PRODUCTION o Sandbox.
  • L'identità viene verificata di nuovo a ogni avvio. Se qualcosa non corrisponde, il connettore preferisce non avviarsi piuttosto che indovinare.
  • La tua chiave vive nel deposito del tuo computer, cioè macOS Keychain o Windows Credential Manager, mai in un file di testo in chiaro.

Se una chiave di accesso è stata condivisa per errore, ad esempio in una chat, uno screenshot o un ticket, riemettila nel portale.

Parte A: Creare l'applicazione nel portale sviluppatori

La parte A si svolge interamente nel portale sviluppatori, su developer.sportalliance.com.

  1. Registrati su developer.sportalliance.com, con email e password oppure con Google. Se non hai ancora un account, troverai Register here sotto il bottone di accesso.

Pagina di accesso del portale sviluppatori con il link Register here sotto il bottone di accesso

  1. Al primo accesso decidi a quale organizzazione appartieni. Se la tua azienda ha già un account partner, chiedi l'accesso al suo amministratore. Altrimenti scegli Create New Partner Account, inserisci il nome del partner e dell'azienda, accetta i termini e condizioni e salva con Save.

Schermata di benvenuto al primo accesso con l'opzione Create New Partner Account

Modulo per il nome del partner, il nome dell'azienda e la casella dei termini e condizioni

  1. Scegli il brand corrispondente nel menu a tendina in alto, Magicline o PerfectGym. Poi apri Sandbox / Details e clicca su Request Sandbox Credentials. Dopo 2-3 minuti il tuo studio di prova è pronto, completamente separato dai dati reali.

Dettagli del sandbox prima del provisioning, un clic lo avvia

  1. Apri Sandbox / Applications e clicca su Add New Application.

Panoramica di Sandbox Applications con il bottone Add New Application

  1. Nella finestra di dialogo, scegli il tipo di applicazione Generic, inserisci un nome, ad esempio «MCP», e indica l'indirizzo email di attivazione. A quell'indirizzo arriverà poi l'email di attivazione con il nome del tenant e la chiave di accesso. La chiave si trova in un PDF protetto da password, e trovi quella password nel portale.

Finestra di dialogo per creare un'applicazione con tipo Generic, un nome e l'indirizzo email di attivazione

  1. Apri la nuova applicazione, vai alla scheda Scopes e clicca su Add Scopes. Gli scope arrivano in coppie _READ e _WRITE per area, ad esempio per appuntamenti, check-in, corsi e dati dei clienti. Select All è comodo per la sandbox, ma per la produzione è meglio assegnarli in modo deliberato.

Un'applicazione appena creata senza scope assegnati e quindi senza accesso

Selezione degli scope con coppie READ e WRITE per area

Gli scope che scegli qui sono il limite assoluto di ciò che il connettore potrà mai raggiungere, indipendentemente da cosa chiedi all'assistente. Concedili con parsimonia, puoi sempre aggiungerne altri in seguito.

Parte B: Attivare l'integrazione nello studio

  1. Su Sandbox / Details ora sono pronte le tue credenziali: l'indirizzo web (https://<tenant>.web.sandbox.magicline.com per Magicline, https://<tenant>.web.sandbox.perfectgym.com per PerfectGym Next), il nome utente adminuser, la password, che riveli con l'icona dell'occhio, e l'URL di base (https://<tenant>.open-api.sandbox.magicline.com oppure https://<tenant>.open-api.sandbox.perfectgym.com rispettivamente). Accedi con quel nome utente e quella password.

Dettagli del sandbox con le credenziali una volta terminato il provisioning

  1. Nello studio, vai su Settings / Integrations / Overview. La tua applicazione appare lì accanto ai partner integrati. Clicca su Activate nella sua riga.

Panoramica delle integrazioni nello studio con la tua applicazione e il bottone Activate

La finestra di dialogo di attivazione chiede quali dati dei clienti lo studio condivide con l'integrazione, in due gruppi: clienti esistenti (membri, contatti interessati, ex membri) e nuovi clienti (nuovi membri, nuovi contatti interessati), cinque caselle in totale. Tutto è disattivato per impostazione predefinita. Seleziona tutte le cinque caselle e solo dopo clicca su Activate, altrimenti il connettore vedrà uno studio vuoto. Dopo riceverai l'email di attivazione con il nome del tenant e la chiave.

Passaggio di consenso dell'attivazione con le caselle di condivisione dei dati

Parte C: Configurare il connettore nel terminale

  1. Installa uv. Porta con sé un proprio ambiente Python, non ti serve altro.
    • macOS e 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. Apri l'email di attivazione e, al suo interno, il PDF con la password dal portale. Tieni a portata di mano il nome del tenant e la chiave.
  3. Esegui uvx sportalliance-mcp setup. La procedura guidata chiede prima la piattaforma e offre Magicline e PerfectGym Next come opzioni.
  4. Inserisci il nome del tenant e scegli l'ambiente: Sandbox per lo studio di prova della parte B, Production per l'uso reale. Ogni opzione ti mostra l'indirizzo API completamente risolto per poterlo controllare. Poi incolla la chiave dal PDF, l'input resta nascosto. La procedura guidata valida la chiave in tempo reale rispetto all'API e ti mostra quale studio apre realmente. Il server parte per impostazione predefinita in modalità sicura di sola lettura, e la chiave viene salvata nel portachiavi del tuo sistema operativo.
  5. Segue poi la domanda facoltativa su una connessione a un data warehouse. È una funzione avanzata per clienti enterprise con un proprio accesso a un data warehouse, e la documentazione tecnica ne copre i dettagli. Senza quell'accesso, salta la domanda con Invio, e non cambia altro.
  6. Infine, scegli le app di IA che vuoi configurare. Le app già rilevate sono preselezionate, e confermi con Invio. Per Claude Code c'è un'altra domanda su quanto pre-approvare. La scelta consigliata è: gli strumenti di lettura non personali funzionano senza chiedere, mentre i dati dei membri e le modifiche continuano a chiedere prima.

La configurazione è quindi completata. Riavvia la tua app di IA e gli strumenti saranno disponibili.

Testare la configurazione

Riavvia la tua app di IA e fai una domanda semplice, ad esempio «Quali corsi ci sono in programma per domani?». Se ricevi una risposta dal tuo studio, gli strumenti funzionano come previsto.

Parte D: Passare alla produzione

Una volta che la sandbox funziona come desideri, ripeti gli stessi passaggi per Application, Details e Scopes nella scheda Production del portale e invia l'applicazione per la revisione.

Presta particolare attenzione agli scope qui: ciò che concedi si applica a ogni studio che attiva l'integrazione.

Dopo l'approvazione di Sport Alliance, gli studi reali possono attivare l'integrazione esattamente come al passaggio 8. L'attivazione fornisce di nuovo una chiave in un PDF protetto da password. Esegui quindi di nuovo uvx sportalliance-mcp setup, questa volta con il tenant e la chiave di produzione, e scegli Production come ambiente.

Il connettore nella vita quotidiana

Alla reception:

  • «Prenota Jonas Weber al corso di Spin di stasera.»
  • «Registra l'ingresso di Anna Schmidt.»
  • «Quando può Anna cancellare il suo contratto al più tardi?»
  • «Qual è il suo saldo, e cosa deve pagare successivamente?»
  • «Estendi la sua pausa di un mese, quanto costerebbe?»
  • «Crea un contatto interessato per Max Mustermann, max@example.com, e prenotagli una sessione di prova gratuita per domani mattina.»

In ufficio:

  • «Quanto è affollata la palestra in questo momento?»
  • «Quali corsi ci sono domani, e quali hanno ancora posti liberi?»
  • «Mostra il saldo del conto e i prossimi addebiti del cliente 10023.»
  • «Annota quella chiamata sulla sua scheda.»

Prima di ogni prenotazione o modifica del contratto, l'assistente verifica automaticamente se l'azione è davvero possibile per quel membro. Corsi riservati, regole di abbonamento e limiti di pausa vengono rispettati automaticamente.

Se un corso o un'offerta «non esiste», di solito è perché non è ancora stato creato in ufficio. Il connettore può leggere e prenotare l'inventario esistente, ma creare nuovi corsi e offerte resta un compito dell'ufficio.

Modificare i permessi in seguito

Il comando uvx sportalliance-mcp permissions è sufficiente per attivare o disattivare i livelli di accesso, o per disattivare singole funzioni, ad esempio mantenere la prenotazione dei corsi ma escludere completamente la cancellazione dei contratti. Non devi rifare la configurazione per questo.

Riavvia la tua app di IA dopo ogni modifica alle impostazioni.

Messaggi comuni e il loro significato

  • «The tenant does not exist on this host»: gli studi sandbox e di produzione si trovano a indirizzi diversi. Il tuo studio esiste, solo nell'altro ambiente. La procedura guidata di configurazione ti offre il cambio con un solo tasto.
  • «The key is valid, but the integration has no scope…»: la chiave funziona, ma all'applicazione non è mai stato concesso alcun permesso nel portale. Torna al passaggio 6, aggiungi gli scope necessari e riprova.
  • «The API rejected the key (401/403)»: il tenant e la chiave non corrispondono tra loro. Entrambi provengono dalla stessa email di attivazione, controllali di nuovo lì. Se usi entrambe le piattaforme, assicurati che la chiave non provenga dall'altra.
  • La connessione non si avvia affatto e mostra «STOPPING»: la chiave apre uno studio diverso da quello per cui questa connessione è stata configurata. È il controllo di identità che fa esattamente ciò che deve fare. Esegui di nuovo la procedura guidata di configurazione per quella piattaforma.
  • Mancano strumenti nell'app di IA: le funzionalità per i dati dei membri e per le modifiche appaiono solo quando il loro livello è attivato. Controlla i permessi e poi riavvia l'app di IA.
  • I dati di un membro tornano come «permission denied»: alcuni membri si oppongono alla condivisione dei loro dati con terzi. È un loro diritto, la piattaforma lo rispetta, e il connettore lo segnala invece di riprovare.

Collegare altri studi o piattaforme

Se vuoi collegare altri studi o l'altra piattaforma, esegui semplicemente di nuovo la configurazione. Entrambi funzioneranno allora fianco a fianco nella stessa app di IA, distinti per colore.

Avviso: Questo articolo è stato creato con l'aiuto dell'intelligenza artificiale e tradotto automaticamente senza revisione editoriale. Ci scusiamo per eventuali errori.