Saltar al contenido principal

Configura y usa el Sport Alliance MCP

Actualización

En este artículo aprenderás …

  • qué puede hacer el conector y qué apps de IA lo admiten
  • cómo configurarlo paso a paso en un entorno sandbox
  • qué niveles de permisos existen y cómo los controlas
  • cómo pasar de la prueba en sandbox al uso en producción
  • qué significan los mensajes más habituales

Contenido

Guía rápida

  1. Regístrate en developer.sportalliance.com y crea una cuenta de partner.
  2. Elige tu marca, solicita las credenciales de sandbox y espera entre 2 y 3 minutos.
  3. Crea una aplicación y asígnale los scopes que necesites.
  4. Activa la integración en el estudio sandbox y marca todas las casillas de consentimiento.
  5. Instala uv en la terminal.
  6. Abre el correo de activación, abre el PDF con la contraseña del portal y ten a mano el nombre del tenant y la clave.
  7. Ejecuta uvx sportalliance-mcp setup y sigue las preguntas del asistente.
  8. Reinicia tu app de IA y pruébalo con una pregunta sencilla.

Qué puede hacer el conector

El conector conecta un asistente de IA con Magicline o PerfectGym Next. Formulas tu solicitud en lenguaje normal, el conector la convierte en acciones comprobadas y controladas por permisos, y te devuelve la respuesta. No necesitas programar.

Son compatibles Claude Desktop, Claude Code, Cursor, Windsurf, Gemini CLI y Antigravity.

Así son las solicitudes típicas:

  • «Reserva a Jonas Weber en la clase de Spin de esta noche.»
  • «Registra la entrada de Anna Schmidt.»
  • «Pausa el contrato de Anna en agosto, vacaciones.»
  • «¿Qué clases hay mañana y cuáles tienen plazas libres?»
  • «¿Qué ofertas de socios vendemos, y cuánto costaría Premium para el cliente 10023?»

Una sola instalación puede atender ambas plataformas a la vez. Distintos estudios y cuentas funcionan en paralelo, cada uno con su propia clave y sus propios permisos.

El conector es válido para Magicline y PerfectGym Next. No funciona con el producto clásico de PerfectGym en perfectgym.pl, que es un sistema distinto.

Requisitos previos

  • Una de las apps de IA mencionadas arriba
  • Una ventana de terminal: la app Terminal en Mac, PowerShell en Windows
  • Un buzón de correo que puedas consultar, porque la clave de acceso llega por email
  • Unos 30 minutos, solo una vez

Todos los pasos de las partes A a C se realizan en un sandbox, un entorno de prueba dedicado sin datos reales. Solo la parte D te lleva a producción.

Permisos y medidas de seguridad

El conector trabaja con tres niveles de acceso. Siempre empieza en el nivel 1, y tienes que activar los niveles superiores de forma deliberada.

  1. Solo lectura (predeterminado, siempre activo): horarios de clases, plazas libres, ofertas de socios e información del estudio. Sin datos de socios, y nada se puede modificar.
  2. Datos de socios (opcional): perfiles, contratos, saldos e historial de check-in. Son datos personales reales de socios reales, así que activa este nivel solo cuando estés preparado para esa responsabilidad.
  3. Realizar cambios (opcional): reservar clases, registrar entradas de socios, crear interesados, pausar contratos. Son acciones reales en tu estudio, y el asistente siempre te muestra antes qué va a hacer.

Cuatro medidas de seguridad están siempre activas, sea cual sea el nivel elegido:

  • Las acciones importantes, como cancelar un contrato, firmar una membresía o exportar datos financieros, nunca se aprueban automáticamente. Una persona confirma cada una de ellas.
  • Cada respuesta indica el estudio del que procede, con una etiqueta clara de PRODUCTION o Sandbox.
  • La identidad se comprueba de nuevo en cada inicio. Si algo no coincide, el conector prefiere no iniciarse antes que adivinar.
  • Tu clave vive en el almacén propio de tu ordenador, es decir, en macOS Keychain o en Windows Credential Manager, nunca en un archivo de texto sin cifrar.

Si una clave de acceso se compartió por error, por ejemplo en un chat, una captura de pantalla o un ticket, vuelve a emitirla en el portal.

Parte A: Crear la aplicación en el portal de desarrolladores

La parte A se realiza por completo en el portal de desarrolladores, en developer.sportalliance.com.

  1. Regístrate en developer.sportalliance.com, con email y contraseña o con Google. Si aún no tienes cuenta, encontrarás Register here debajo del botón de inicio de sesión.

Página de inicio de sesión del portal de desarrolladores con el enlace Register here debajo del botón de inicio de sesión

  1. En tu primer inicio de sesión decides a qué organización perteneces. Si tu empresa ya tiene una cuenta de partner, pide acceso a su administrador. En caso contrario, elige Create New Partner Account, introduce el nombre del partner y de la empresa, acepta los términos y condiciones y guarda con Save.

Pantalla de bienvenida en el primer inicio de sesión con la opción Create New Partner Account

Formulario para el nombre del partner, el nombre de la empresa y la casilla de términos y condiciones

  1. Elige la marca correspondiente en el desplegable de marca de arriba, Magicline o PerfectGym. Después abre Sandbox / Details y haz clic en Request Sandbox Credentials. Al cabo de 2 a 3 minutos tu propio estudio de prueba estará listo, completamente separado de los datos reales.

Detalles del sandbox antes de la provisión, un clic la inicia

  1. Abre Sandbox / Applications y haz clic en Add New Application.

Vista de Sandbox Applications con el botón Add New Application

  1. En el diálogo, elige el tipo de aplicación Generic, escribe un nombre, por ejemplo «MCP», e introduce la dirección de email de activación. A esa dirección llegará más tarde el correo de activación con el nombre del tenant y la clave de acceso. La clave está dentro de un PDF protegido con contraseña, y encontrarás esa contraseña en el portal.

Diálogo para crear una aplicación con tipo Generic, un nombre y la dirección de email de activación

  1. Abre la nueva aplicación, ve a la pestaña Scopes y haz clic en Add Scopes. Los scopes vienen en pares _READ y _WRITE por área, por ejemplo para citas, check-in, clases y datos de clientes. Select All es cómodo para el sandbox, pero para producción es mejor asignarlos de forma deliberada.

Una aplicación recién creada sin scopes asignados y por tanto sin acceso

Selección de scopes con pares READ y WRITE por área

Los scopes que elijas aquí son el límite absoluto de lo que el conector podrá alcanzar, sin importar lo que le pidas al asistente. Concédelos con moderación, siempre puedes añadir más adelante.

Parte B: Activar la integración en el estudio

  1. En Sandbox / Details ya tienes tus credenciales listas: la dirección web (https://<tenant>.web.sandbox.magicline.com para Magicline, https://<tenant>.web.sandbox.perfectgym.com para PerfectGym Next), el nombre de usuario adminuser, la contraseña, que puedes ver con el icono del ojo, y la URL base (https://<tenant>.open-api.sandbox.magicline.com o https://<tenant>.open-api.sandbox.perfectgym.com respectivamente). Inicia sesión con ese usuario y contraseña.

Detalles del sandbox con las credenciales una vez finalizada la provisión

  1. En el estudio, ve a Settings / Integrations / Overview. Tu propia aplicación aparece ahí junto a los partners integrados. Haz clic en Activate en su fila.

Vista de integraciones en el estudio con tu propia aplicación y el botón Activate

El diálogo de activación pregunta qué datos de clientes comparte el estudio con la integración, en dos grupos: clientes existentes (socios, interesados, exsocios) y clientes nuevos (nuevos socios, nuevos interesados), cinco casillas en total. Todo está desactivado por defecto. Marca las cinco casillas y solo entonces haz clic en Activate, de lo contrario el conector verá un estudio vacío. Después recibirás el correo de activación con el nombre del tenant y la clave.

Paso de consentimiento de la activación con las casillas de compartición de datos

Parte C: Configurar el conector en la terminal

  1. Instala uv. Trae su propio entorno de Python, no necesitas nada más.
    • macOS y 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. Abre el correo de activación y, dentro, el PDF con la contraseña del portal. Ten a mano el nombre del tenant y la clave.
  3. Ejecuta uvx sportalliance-mcp setup. El asistente primero pregunta por la plataforma y ofrece Magicline y PerfectGym Next como opciones.
  4. Introduce el nombre del tenant y elige el entorno: Sandbox para el estudio de prueba de la parte B, Production para el uso real. Cada opción te muestra la dirección de la API completamente resuelta para que la compruebes. Después pega la clave del PDF, la entrada permanece oculta. El asistente valida la clave en tiempo real contra la API y te muestra qué estudio abre realmente. El servidor arranca por defecto en modo seguro de solo lectura, y la clave se guarda en el llavero de tu sistema operativo.
  5. A continuación llega la pregunta opcional sobre la conexión con un almacén de datos. Es una función avanzada para clientes enterprise con su propio acceso a un almacén de datos, y la documentación técnica cubre los detalles. Sin ese acceso, omite la pregunta con Enter y no cambia nada más.
  6. Por último, elige las apps de IA que quieres configurar. Las apps ya detectadas aparecen preseleccionadas, y confirmas con Enter. Para Claude Code hay una pregunta más sobre cuánto aprobar de antemano. La opción recomendada es: las herramientas de lectura no personales se ejecutan sin preguntar, mientras que los datos de socios y los cambios siguen preguntando primero.

La configuración ya está lista. Reinicia tu app de IA y las herramientas estarán disponibles.

Probar la configuración

Reinicia tu app de IA y haz una pregunta sencilla, por ejemplo «¿Qué clases hay programadas para mañana?». Si recibes una respuesta de tu estudio, las herramientas funcionan como se espera.

Parte D: Pasar a producción

Cuando el sandbox funcione como quieres, repite los mismos pasos de Application, Details y Scopes en la pestaña Production del portal y envía la aplicación a revisión.

Presta especial atención a los scopes aquí: lo que concedas se aplicará a cada estudio que active la integración.

Tras la aprobación de Sport Alliance, los estudios reales pueden activar la integración igual que en el paso 8. La activación entrega de nuevo una clave en un PDF protegido con contraseña. Después vuelve a ejecutar uvx sportalliance-mcp setup, esta vez con el tenant y la clave de producción, y elige Production como entorno.

El conector en el día a día

En la recepción:

  • «Reserva a Jonas Weber en la clase de Spin de esta noche.»
  • «Registra la entrada de Anna Schmidt.»
  • «¿Cuándo puede Anna cancelar su contrato como máximo?»
  • «¿Cuál es su saldo, y qué le corresponde pagar a continuación?»
  • «Amplía su pausa un mes, ¿cuánto costaría?»
  • «Crea un interesado para Max Mustermann, max@example.com, y resérvale una sesión de prueba gratuita para mañana por la mañana.»

En la oficina:

  • «¿Cómo está de ocupado el gimnasio ahora mismo?»
  • «¿Qué clases hay mañana y cuáles tienen plazas libres?»
  • «Muéstrame el saldo y los próximos cargos del cliente 10023.»
  • «Anota esa llamada en su ficha.»

Antes de cualquier reserva o cambio de contrato, el asistente comprueba automáticamente si la acción es posible para ese socio. Las clases restringidas, las reglas de membresía y los límites de pausa se respetan de forma automática.

Si una clase o una oferta «no existe», normalmente es que aún no se ha creado en la oficina. El conector puede leer y reservar el inventario existente, pero crear nuevas clases y ofertas sigue siendo una tarea de la oficina.

Cambiar los permisos más adelante

El comando uvx sportalliance-mcp permissions basta para activar o desactivar niveles de acceso, o para desactivar funciones concretas, por ejemplo mantener la reserva de clases pero excluir por completo la cancelación de contratos. No necesitas repetir la configuración para esto.

Reinicia tu app de IA después de cualquier cambio en la configuración.

Mensajes habituales y qué significan

  • «The tenant does not exist on this host»: los estudios de sandbox y de producción están en direcciones distintas. Tu estudio existe, solo que en el otro entorno. El asistente de configuración te ofrece el cambio con una sola tecla.
  • «The key is valid, but the integration has no scope…»: la clave funciona, pero a la aplicación nunca se le concedieron permisos en el portal. Vuelve al paso 6, añade los scopes que necesites e inténtalo de nuevo.
  • «The API rejected the key (401/403)»: el tenant y la clave no coinciden. Ambos proceden del mismo correo de activación, compruébalos ahí de nuevo. Si usas ambas plataformas, asegúrate de que la clave no sea de la otra.
  • La conexión no se inicia y muestra «STOPPING»: la clave abre un estudio distinto al configurado para esta conexión. Esa es la comprobación de identidad haciendo justo lo que debe. Vuelve a ejecutar el asistente de configuración para esa plataforma.
  • Faltan herramientas en la app de IA: las capacidades de datos de socios y de cambios solo aparecen cuando su nivel está activado. Comprueba los permisos y reinicia después la app de IA.
  • Los datos de un socio vuelven como «permission denied»: algunos socios se oponen a que sus datos se compartan con terceros. Es su derecho, la plataforma lo respeta, y el conector lo informa en lugar de reintentarlo.

Conectar más estudios o plataformas

Si quieres conectar estudios adicionales o la otra plataforma, simplemente vuelve a ejecutar la configuración. Ambos funcionarán entonces en paralelo dentro de la misma app de IA, diferenciados por color.

Aviso: Este artículo se ha creado con ayuda de inteligencia artificial y traducido automáticamente sin revisión editorial. Disculpa los posibles errores.