Saltar al contenido principal

KSI MCP – Guía de Conexión (Genérica)

KSI MCP – Cómo Conectar tu Asistente de IA​

Objetivo​

Esta guía te explica cómo conectar un asistente de IA (Claude, ChatGPT, Gemini o cualquier cliente compatible con MCP) al servidor MCP de KSI, para que pueda consultar directamente los indicadores de tus tiendas —tráfico, colas, tiempo de permanencia, conversión de ventas, zonas y más— y convertirlos en reportes, comparativas y análisis en lenguaje natural.

MCP (Model Context Protocol) es el estándar abierto que permite a los asistentes de IA usar herramientas externas de forma segura. El servidor MCP de KSI expone los datos de tu cuenta como un conjunto de herramientas; tu asistente decide cuándo llamarlas según lo que le pidas.

Requisitos​

Antes de conectarte, asegúrate de contar con:

  • Una cuenta válida en la plataforma KSI
  • Tu token de API de KSI (ver API – Guía de Primeros Pasos)
  • Un cliente de IA compatible con MCP (Claude, ChatGPT, Gemini u otro cliente MCP)

👉 URL del servidor MCP:

  • https://mcp.ksivision.com/api/mcp

1. Obtén tu Token de API​

El servidor MCP se autentica con el mismo token Bearer que usa la API de KSI.

  1. Ve a "Mi Perfil" en la plataforma KSI
  2. Selecciona "Generar nuevo token"
  3. Copia el token y guárdalo de forma segura — trátalo como una contraseña

Cada usuario debe conectarse con su propio token: el asistente solo verá las tiendas y datos a los que ese token tiene acceso.

2. Conectar con Inicio de Sesión (OAuth) — Claude.ai, ChatGPT, Gemini​

La mayoría de las apps de IA y clientes web soportan OAuth 2.1 con descubrimiento automático. Solo necesitas la URL del servidor — el cliente te guiará a una pantalla de inicio de sesión de KSI la primera vez.

  1. En tu asistente de IA, busca Configuración → Conectores (o Integraciones / Herramientas, según el cliente)
  2. Elige "Agregar conector personalizado" e ingresa la URL del servidor MCP: https://mcp.ksivision.com/api/mcp
  3. El cliente abre automáticamente la pantalla de inicio de sesión de KSI
  4. Pega tu token de API y selecciona Autorizar
  5. Serás redirigido de vuelta a tu asistente — el conector ya está activo

No necesitarás pegar el token nuevamente hasta que expire (los tokens de acceso duran 30 días y se renuevan automáticamente mientras sigas usando el conector).

3. Conectar con un Token Bearer Estático — Claude Code, integraciones a medida​

Algunos clientes (CLIs de desarrollo, scripts propios, integraciones de API) se conectan con un header fijo en lugar de un inicio de sesión interactivo.

Claude Code (CLI)​

claude mcp add --transport http ksi https://mcp.ksivision.com/api/mcp \
  --header "Authorization: Bearer <TU_TOKEN_KSI>"

Cliente MCP HTTP genérico (archivo de configuración)​

{
  "mcpServers": {
    "ksi": {
      "type": "http",
      "url": "https://mcp.ksivision.com/api/mcp",
      "headers": { "Authorization": "Bearer <TU_TOKEN_KSI>" }
    }
  }
}

4. Primeros Pasos Después de Conectar​

Empieza siempre con la herramienta de diagnóstico de cuenta. Pídele a tu asistente:

"Diagnostica mi cuenta de KSI."

Esto devuelve el tipo de espacio (retail, mall, aeropuerto…), los indicadores globales habilitados en la cuenta y qué capacidades tiene cada tienda (ventas, colas, zonas, sublocations). Las cuentas varían mucho — esto le indica a tu asistente qué puede pedir con seguridad antes de ejecutar un análisis.

Ejemplos de preguntas​

  • "Compara el tráfico y la conversión de mis tiendas en junio, agrupado por etiqueta."
  • "¿En qué ventanas de día y hora estoy perdiendo ventas por colas largas en la tienda 661?"
  • "¿Abrir más cajas mejoraría la conversión en horas pico?"
  • "Ranking de tiendas del mall por conversión, agrupado por categoría."

5. Checklist Antes de Usar el MCP​

  • Tienes un token de API de KSI válido
  • Confirmaste la URL del servidor MCP: https://mcp.ksivision.com/api/mcp
  • Completaste el inicio de sesión (OAuth) o configuraste el header Bearer estático
  • Ejecutaste ksi_diagnose_account (o le pediste a tu asistente que "diagnostique mi cuenta") antes de pedir KPIs
  • Entiendes que el token es personal — cada usuario se conecta con el suyo

Notas de Seguridad​

  • El servidor MCP es de solo lectura: consulta indicadores y nunca modifica configuración, cámaras ni datos
  • Tu token viaja con cada solicitud y nunca se almacena en el servidor MCP
  • El asistente solo ve las tiendas y datos a los que tu token tiene acceso

Soporte​

Si necesitas ayuda para conectar tu asistente de IA, generar un token o resolver un problema con algún cliente en particular:

📧 ksi.support@ksivision.com

El equipo de soporte de KSI puede ayudarte con asistencia técnica y mejores prácticas.