Configuración remota

lean-ctx se ejecuta como un servidor MCP por stdio - tu cliente de IA lo inicia como un subproceso local. Para servidores remotos, contenedores o entornos headless, puedes tunelizar la conexión sobre SSH. No se necesita ningún componente de servidor adicional.

Túnel SSH (recomendado)

El enfoque más simple: configura tu cliente de IA para ejecutar lean-ctx vía SSH. El protocolo MCP fluye por stdin/stdout de SSH - sin puertos que abrir, sin HTTP, sin autenticación que gestionar. SSH maneja el cifrado y la autenticación de forma nativa.

1. Instala lean-ctx en el servidor remoto

Conéctate por SSH a tu servidor e instala lean-ctx:

ssh user@server
cargo install lean-ctx
# or download pre-built binary:
curl -fsSL https://leanctx.com/install.sh | sh

2. Prueba la conexión

Verifica que lean-ctx funciona por SSH. Puedes reenviar el servidor MCP directamente o tunelizar el dashboard:

# Terminal 1: SSH tunnel (keeps running)
ssh -L 3333:localhost:3333 user@server "lean-ctx dashboard --port 3333"

# Or just forward the MCP stdio over SSH:
ssh user@server "lean-ctx"

3. Configura tu cliente de IA

Haz que la configuración MCP de tu cliente de IA ejecute lean-ctx vía SSH. Esto funciona con Cursor, Claude Code, Windsurf y cualquier cliente compatible con MCP:

// ~/.cursor/mcp.json or ~/.claude.json
{
  "mcpServers": {
    "lean-ctx": {
      "command": "ssh",
      "args": ["user@server", "lean-ctx"]
    }
  }
}

Esto indica al cliente que ejecute ssh user@server "lean-ctx" en lugar de un lean-ctx local. El protocolo MCP fluye de forma transparente sobre la conexión SSH - stdin/stdout se tuneliza automáticamente.

Reenvío de puertos (Dashboard)

Si quieres acceder al dashboard de lean-ctx (Observatory) desde tu navegador local mientras lean-ctx se ejecuta en un servidor remoto, usa reenvío de puertos por SSH:

Configuración SSH persistente

# ~/.ssh/config
Host dev-server
  HostName 192.168.1.100
  User developer
  LocalForward 3333 localhost:3333
  ServerAliveInterval 60
  ServerAliveCountMax 3

Luego conéctate e inicia el dashboard:

ssh dev-server "lean-ctx dashboard --port 3333"
# Dashboard now available at http://localhost:3333

VS Code Remote SSH

Si usas VS Code con la extensión Remote - SSH, lean-ctx funciona automáticamente - el servidor MCP se ejecuta en la máquina remota igual que cualquier comando del terminal. Instala lean-ctx en la máquina remota, ejecuta lean-ctx setup y se configurará para ese entorno.

Docker / Contenedores

Para desarrollo en contenedores, monta el binario de lean-ctx y su directorio de datos dentro del contenedor:

# Mount lean-ctx binary into your dev container
docker run -it \
  -v $(which lean-ctx):/usr/local/bin/lean-ctx:ro \
  -v ~/.lean-ctx:/root/.lean-ctx \
  your-dev-image bash

Para Docker Compose, añade los volúmenes a tu servicio:

# docker-compose.yml
services:
  dev:
    image: your-dev-image
    volumes:
      - ./:/workspace
      - lean-ctx-bin:/usr/local/bin/lean-ctx:ro
      - ~/.lean-ctx:/root/.lean-ctx

Solución de problemas

La conexión se corta tras inactividad

Las conexiones SSH pueden expirar durante periodos largos de inactividad. Añade ajustes de keepalive:

ssh -o ServerAliveInterval=60 -o ServerAliveCountMax=3 user@server "lean-ctx"

Permission denied en el remoto

Asegúrate de que lean-ctx esté en el PATH del usuario remoto. Si se instaló con cargo install, está en ~/.cargo/bin/lean-ctx. Añade export PATH=\"$HOME/.cargo/bin:$PATH\" al ~/.bashrc o ~/.zshrc del remoto.

Diferencia de versión entre local y remoto

El cliente de IA local y lean-ctx en remoto deberían ejecutar la misma versión para evitar problemas de protocolo. Mantén ambos actualizados:

# Check versions on both machines
lean-ctx --version              # local
ssh user@server "lean-ctx --version"  # remote

Ejecuta diagnósticos en el remoto

Usa lean-ctx doctor en el servidor remoto para verificar la instalación, los hooks de shell y la configuración MCP:

ssh user@server "lean-ctx doctor"