Saltar al contenido principal

Guía de Configuración: Servidor MCP de KSI Vision en Codex

Esta guía detalla los pasos necesarios para conectar el servidor Model Context Protocol (MCP) de KSI Vision a Codex, el agente de programación de OpenAI — tanto la CLI de Codex como la extensión de IDE de Codex (VS Code / Cursor), que comparten el mismo archivo de configuración.

Una vez conectado, Codex puede consultar directamente los indicadores de tus tiendas —tráfico, colas, tiempo de permanencia, conversión de ventas, zonas y más— lo cual es especialmente útil para construir integraciones, dashboards o pipelines de datos sobre los datos de KSI.

1. Requisitos Previos​

Antes de comenzar, asegúrate de contar con:

  • Una cuenta de KSI Vision con acceso para crear tokens de API (si no tienes acceso, solicítalo a ksi.support@ksivision.com).
  • Tu token de API de KSI (ver API – Guía de Primeros Pasos).
  • Codex CLI instalado y con sesión iniciada (npm i -g @openai/codex o la extensión de IDE). Los servidores MCP remotos (HTTP) requieren una versión reciente — ante la duda, actualiza con codex --version / npm update -g @openai/codex.

👉 URL del servidor MCP:

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

2. Agregar el Servidor en el Archivo de Configuración​

Codex lee su configuración de MCP desde:

  • Ruta del archivo: ~/.codex/config.toml (en Windows: C:\Users\<Tu-Usuario>\.codex\config.toml)

Agrega el siguiente bloque:

[mcp_servers.ksi]
url = "https://mcp.ksivision.com/api/mcp"

Si ya tienes otros servidores configurados, simplemente agrega el bloque [mcp_servers.ksi] debajo de ellos. La extensión de IDE usa este mismo archivo, así que el servidor queda disponible allí también.

3. Autenticación​

Opción A – Inicio de sesión OAuth (recomendada)​

  1. En tu terminal, ejecuta:

    codex mcp login ksi

  2. Tu navegador abre la pantalla de inicio de sesión de KSI.

  3. Pega tu token de API de KSI y selecciona Autorizar.

  4. De vuelta en la terminal, el servidor aparece como autenticado.

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).

Opción B – Token Bearer estático (entornos automatizados / CI)​

Referencia una variable de entorno que contenga tu token — no escribas el token directamente en el archivo:

[mcp_servers.ksi]
url = "https://mcp.ksivision.com/api/mcp"
bearer_token_env_var = "KSI_TOKEN"

Luego define la variable en tu shell antes de iniciar Codex:

# macOS / Linux
export KSI_TOKEN="<TU_TOKEN_KSI>"

# Windows (PowerShell)
$env:KSI_TOKEN = "<TU_TOKEN_KSI>"
nota

El soporte de MCP en Codex evoluciona rápido y los parámetros de los comandos pueden variar entre versiones. Ejecuta codex mcp --help para ver las opciones disponibles en tu versión — también puedes gestionar los servidores con codex mcp add / codex mcp list en lugar de editar el archivo manualmente.

4. Verificación​

  1. Inicia una sesión de Codex (codex en tu terminal, o abre la extensión de IDE).
  2. Ejecuta /mcp para confirmar que el servidor ksi aparece como conectado y que sus herramientas están listadas.
  3. Haz tu primera pregunta:

"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) — así Codex sabe 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."
  • "Trae el tráfico por tienda de la semana pasada y arma un resumen en CSV."
  • "¿En qué ventanas de día y hora estoy perdiendo ventas por colas largas en la tienda 661?"

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.
  • Codex solo ve las tiendas y datos a los que tu token tiene acceso — cada usuario debe conectarse con su propio token.

Soporte​

Si necesitas ayuda para conectar Codex, generar un token o resolver algún problema:

📧 ksi.support@ksivision.com