Configuration distante

lean-ctx s’exécute comme un serveur MCP sur stdio - votre client IA le lance comme un sous-processus local. Pour des serveurs distants, des conteneurs ou des environnements headless, vous pouvez transporter la connexion via SSH. Aucun composant serveur supplémentaire n’est nécessaire.

Tunnel SSH (recommandé)

L’approche la plus simple : configurez votre client IA pour exécuter lean-ctx via SSH. Le protocole MCP passe par stdin/stdout de SSH - pas de ports à ouvrir, pas de HTTP, pas d’authentification à gérer. SSH gère nativement le chiffrement et l’authentification.

1. Installer lean-ctx sur le serveur distant

Connectez-vous en SSH à votre serveur et installez lean-ctx :

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

2. Tester la connexion

Vérifiez que lean-ctx fonctionne via SSH. Vous pouvez soit exécuter le serveur MCP directement, soit tunneliser le tableau de bord :

# 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. Configurer votre client IA

Pointez la configuration MCP de votre client IA pour lancer lean-ctx via SSH. Cela fonctionne avec Cursor, Claude Code, Windsurf et tout client compatible MCP :

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

Cela indique au client de lancer ssh user@server "lean-ctx" au lieu d’un lean-ctx local. Le protocole MCP transite de manière transparente via la connexion SSH - stdin/stdout est tunnelisé automatiquement.

Redirection de ports (Dashboard)

Si vous souhaitez accéder au dashboard lean-ctx (Observatory) depuis votre navigateur local pendant que lean-ctx s’exécute sur un serveur distant, utilisez la redirection de ports SSH :

Configuration SSH persistante

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

Puis connectez-vous et démarrez le dashboard :

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

VS Code Remote SSH

Si vous utilisez VS Code avec l’extension Remote - SSH, lean-ctx fonctionne automatiquement - le serveur MCP s’exécute sur la machine distante comme n’importe quelle commande du terminal. Installez lean-ctx sur la machine distante, exécutez lean-ctx setup, et tout se configure pour l’environnement distant.

Docker / Conteneurs

Pour le développement en conteneur, montez le binaire lean-ctx et son répertoire de données dans votre conteneur :

# 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

Avec Docker Compose, ajoutez les volumes à votre service :

# 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

Dépannage

La connexion se coupe après une période d’inactivité

Les connexions SSH peuvent expirer pendant de longues périodes d’inactivité. Ajoutez des paramètres keepalive :

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

Permission denied sur le distant

Assurez-vous que lean-ctx est dans le PATH de l’utilisateur distant. S’il est installé via cargo install, il se trouve dans ~/.cargo/bin/lean-ctx. Ajoutez export PATH=\"$HOME/.cargo/bin:$PATH\" au ~/.bashrc ou ~/.zshrc du distant.

Différence de version entre local et distant

Le client IA local et lean-ctx côté distant devraient exécuter la même version afin d’éviter des problèmes de protocole. Gardez les deux à jour :

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

Exécuter des diagnostics sur le distant

Utilisez lean-ctx doctor sur le serveur distant pour vérifier l’installation, les hooks shell et la configuration MCP :

ssh user@server "lean-ctx doctor"