Configuração remota

O lean-ctx roda como um servidor MCP via stdio - seu cliente de IA o inicia como um subprocesso local. Para servidores remotos, contêineres ou ambientes headless, você pode tunelar a conexão via SSH. Não é necessário nenhum componente extra de servidor.

Túnel SSH (recomendado)

A abordagem mais simples: configure seu cliente de IA para executar lean-ctx via SSH. O protocolo MCP flui pelo stdin/stdout do SSH - sem abrir portas, sem HTTP, sem gerenciar autenticação. O SSH lida nativamente com criptografia e autenticação.

1. Instale o lean-ctx no servidor remoto

Acesse seu servidor via SSH e instale o lean-ctx:

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

2. Teste a conexão

Verifique se o lean-ctx funciona via SSH. Você pode executar o servidor MCP diretamente ou tunelar o 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. Configure seu cliente de IA

Aponte a configuração MCP do seu cliente de IA para executar o lean-ctx via SSH. Isso funciona com Cursor, Claude Code, Windsurf e qualquer cliente compatível com MCP:

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

Isso faz o cliente iniciar ssh user@server "lean-ctx" em vez de um lean-ctx local. O protocolo MCP flui de forma transparente pela conexão SSH - stdin/stdout é tunelado automaticamente.

Port forwarding (Dashboard)

Se você quiser acessar o dashboard do lean-ctx (Observatory) no seu navegador local enquanto o lean-ctx roda em um servidor remoto, use port forwarding via SSH:

Configuração SSH persistente

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

Depois conecte e inicie o dashboard:

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

VS Code Remote SSH

Se você usa o VS Code com a extensão Remote - SSH, o lean-ctx funciona automaticamente - o servidor MCP roda na máquina remota como qualquer comando do terminal. Instale o lean-ctx no remoto, execute lean-ctx setup e ele se configura para o ambiente remoto.

Docker / Contêineres

Para desenvolvimento em contêiner, monte o binário do lean-ctx e o diretório de dados no seu contêiner:

# 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, adicione os volumes ao seu serviço:

# 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

Solução de problemas

A conexão cai após um tempo ocioso

Conexões SSH podem expirar durante longos períodos de ociosidade. Adicione configurações de keepalive:

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

Permission denied no remoto

Garanta que lean-ctx esteja no PATH do usuário remoto. Se instalado via cargo install, ele fica em ~/.cargo/bin/lean-ctx. Adicione export PATH=\"$HOME/.cargo/bin:$PATH\" ao ~/.bashrc ou ~/.zshrc do remoto.

Diferença de versão entre local e remoto

O cliente de IA local e o lean-ctx remoto devem rodar a mesma versão para evitar problemas de protocolo. Mantenha ambos atualizados:

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

Execute diagnósticos no remoto

Use lean-ctx doctor no servidor remoto para verificar a instalação, os hooks de shell e a configuração MCP:

ssh user@server "lean-ctx doctor"