Verificando autenticación…

Saltar al contenido principal

Agrega mcp-andes a tu IDE

Esta guía te ayuda a instalar y configurar mcp-andes para trabajar con ANDES directamente desde tu editor (Cursor, Windsurf, VS Code con agentes compatibles, etc.). Está alineada con la guía interactiva de la plataforma ANDES.

¿Qué es mcp-andes?

mcp-andes es la CLI principal de la plataforma ANDES. Conecta tu entorno local con los servicios de ANDES y, mediante el protocolo MCP (Model Context Protocol), permite que tu IDE ejecute acciones como crear aplicaciones, consultar productos o instalar skills sin salir del editor.

Requisitos previos​

Antes de comenzar, verifica que tienes:

Paso 1 — Instalar el gestor uv​

Necesitamos uv para instalar mcp-andes de forma aislada y sin conflictos. Para información siempre actualizada consulta la documentación oficial de uv.

macOS / Linux:

Instalar uv
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

Instalar uv en Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Comprueba que quedó bien instalado:

Verificar uv
uv --version

Paso 2 — Obtener token de Artifactory​

Necesitarás un token personal de Artifactory para instalar mcp-andes desde el índice privado de LATAM.

i. Acceder a Artifactory​

Ingresa a https://artifactoryrepo1.appslatam.com/ui/login/ y autentícate con tu cuenta LATAM usando login de Google.

ii. Generar token​

En la esquina superior derecha abre el User Menu, entra en "Set me up" y selecciona "pypi".

Luego haz clic en "Generate token".

iii. Copiar credenciales​

En la pestaña "install" verás una variable con este formato:

index-url = https://TU.USUARIO:TOKEN@artifactoryrepo1.appslatam.com/...

Copia lo que está antes del @ (es decir, TU.USUARIO:TOKEN) porque lo usarás en los siguientes pasos.

Paso 3 — Instalar y configurar mcp-andes​

Ahora instalaremos la herramienta central de ANDES. Sigue estos tres sub-pasos cuidadosamente.

i. Instalación desde el terminal​

Ejecuta el siguiente comando usando el valor USUARIO:TOKEN que copiaste en el paso anterior (lo que estaba antes del @):

Instalar mcp-andes
uv tool install mcp-andes \
  --index-url "https://USUARIO:TOKEN@artifactoryrepo1.appslatam.com/artifactory/api/pypi/zone_andesai/simple" \
  --extra-index-url "https://pypi.org/simple" \
  --force

ii. Configurar el PATH (solo una vez)​

Para que tu terminal reconozca el comando mcp-andes, añade el directorio de herramientas a tu configuración. Selecciona según tu terminal:

Si usas Zsh (Mac por defecto):

PATH en Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Si usas Bash (Linux / Windows Git Bash):

PATH en Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

iii. Verificación final​

Comprueba que el sistema localiza la herramienta correctamente:

Verificar instalación
which mcp-andes

Resultado esperado: deberías ver una ruta similar a /Users/tu_nombre/.local/bin/mcp-andes.

Paso 4 — Autenticación con Azure AD​

Para habilitar los permisos de creación de aplicaciones, debes vincular tu cuenta corporativa mediante el Device Flow de Microsoft (sin almacenar contraseñas localmente).

i. Iniciar el flujo​

Ejecuta el siguiente comando en tu terminal:

Autenticación Azure AD
mcp-andes test-auth

ii. Sincronización (Device Flow)​

La terminal te proporcionará un código de 8 dígitos y abrirá una ventana en tu navegador:

  1. Copia el código que aparece en la terminal.
  2. Pégalo en la página de inicio de sesión de Microsoft que se abrirá automáticamente.
  3. Inicia sesión con tus credenciales estándar de la compañía.

iii. Confirmación​

Una vez que el navegador confirme el éxito, regresa a tu terminal. Deberías ver un mensaje similar a:

Authentication successful

Paso 5 — Configurar el MCP Server en tu IDE​

Para que tu editor de código pueda comunicarse con el servidor de ANDES, utilizaremos uvx como runtime. Asegúrate de tener tus credenciales de Artifactory a mano (USUARIO:TOKEN del paso 2).

i. Configuración en tu IDE​

Cada IDE tiene su propio archivo de configuración MCP. Los más comunes:

IDEArchivo de configuración
Cursor.cursor/mcp.json en la raíz del proyecto, o ~/.cursor/mcp.json para configuración global
Windsurf~/.codeium/windsurf/mcp_config.json
Claude Code~/.claude/claude_desktop_config.json

En Cursor también puedes llegar desde: Settings → Cursor Settings → Tools & MCP → Add new MCP server.

Agrega este bloque en el archivo correspondiente:

Configuración MCP (mcp-andes)
{
  "mcpServers": {
    "mcp-andes": {
      "command": "uvx",
      "args": ["mcp-andes"],
      "env": {
        "UV_INDEX_URL": "https://USUARIO:TOKEN@artifactoryrepo1.appslatam.com/artifactory/api/pypi/zone_andesai/simple",
        "UV_EXTRA_INDEX_URL": "https://pypi.org/simple"
      }
    }
  }
}

Reemplaza USUARIO:TOKEN con el valor que copiaste en el paso 2 (lo que estaba antes del @).

ii. Verificación​

Guarda los cambios y reinicia o recarga tu IDE. En Cursor, deberías ver mcp-andes en Installed MCP Servers con las tools disponibles para el agente.

Imagen de referencia

Si necesitas validar visualmente la configuración, en Cursor busca Settings → Tools & MCP y confirma que mcp-andes aparece como servidor instalado y habilitado.

Paso 6 — Descargar e instalar Skills​

Para comenzar a desarrollar con AndesDX, instala el paquete de habilidades del ciclo de vida de aplicaciones. El sistema gestionará automáticamente la descarga y descompresión.

i. Ejecución del comando​

Instalar skill de ciclo de vida
mcp-andes install-skills platform/andesdx-app-lifecycle

ii. ¿Qué sucede internamente?​

  • Resolución de versión: el backend identifica y descarga automáticamente la última versión estable disponible.
  • Gestión de archivos: se descarga un paquete .tgz que se descomprime en tu directorio local de trabajo.

iii. Instalación personalizada (opcional)​

Si necesitas una versión específica por compatibilidad:

Instalar versión específica
mcp-andes install-skills platform/andesdx-app-lifecycle@1.2.0

Paso 7 — Crea tu primera aplicación con el Agente​

¡Todo listo! Ahora puedes interactuar con la plataforma directamente desde el chat de tu editor. No necesitas recordar comandos complejos: describe lo que necesitas en lenguaje natural.

i. Verificación del estado de autenticación​

Antes de comenzar, verifica que tu MCP esté correctamente cargado y que el token de tu usuario esté activo. Muchos prompts fallan por una sesión vencida.

Comandos de verificación
# Verificar autenticación
mcp-andes test-auth

# Ver estado detallado del token
mcp-andes token-status

ii. Iniciar la conversación​

Abre una carpeta limpia y vacía en tu IDE antes de comenzar. Una vez que el agente genere tu aplicación, clonará el repositorio directamente en ese espacio de trabajo.

Luego abre un nuevo chat con tu agente de IA y escribe una instrucción clara.

Ejemplos de prompts:

  • "Muéstrame mis productos disponibles en AndesDX"
  • "Quiero crear una nueva aplicación en AndesDX"
  • "Ayúdame a inicializar un proyecto backend con el estándar de la plataforma"
  • "Crea una aplicación Spring Boot con nombre nombre-app en el producto producto creado previamente en el portal"
  • "Crea una aplicación Python FastAPI con nombre nombre-app en el producto producto creado previamente en el portal"
  • "Promueve mi aplicación nombre a producción"

iii. Flujo asistido por el Agente​

Durante la interacción con el chat, el agente te guiará por estos pasos:

  1. Selección de producto: define en qué producto (creado previamente en AndesDX) vas a crear la aplicación.
  2. Identidad y naming: nombre de la app, template (tecnología) y metadatos del proyecto.
  3. Aprovisionamiento: creación de recursos y monitoreo del workflow en tiempo real (visible en Aplicaciones en la plataforma).
  4. Entorno local: clonación del repositorio listo para codificar.

Comandos útiles de referencia​

AcciónComando
Ver estado del tokenmcp-andes token-status
Refrescar tokenmcp-andes refresh-token
Forzar refreshmcp-andes refresh-token --force
Cerrar sesiónmcp-andes logout
Probar conexiónmcp-andes test-connection
Ver configuraciónmcp-andes config-info

Solución de problemas​

mcp-andes no se encuentra en la terminal​

Verifica que agregaste $HOME/.local/bin al PATH y abriste una nueva sesión de terminal:

which mcp-andes

Error al instalar desde Artifactory​

  • Confirma que copiaste USUARIO:TOKEN completo (antes del @).
  • Genera un token nuevo si el anterior expiró.
  • Verifica conectividad a artifactoryrepo1.appslatam.com.

El servidor MCP no aparece en el IDE​

  • Revisa la sintaxis JSON del archivo de configuración.
  • Confirma que UV_INDEX_URL incluye credenciales válidas.
  • Reinicia o recarga el IDE después de guardar cambios.

La autenticación falla o el token expiró​

mcp-andes test-auth
mcp-andes token-status

Soporte​

Si encuentras problemas durante la instalación o configuración, contacta al equipo de Engineering Platform de LATAM Airlines.