Remote Setup

lean-ctx runs as a stdio MCP server - your AI client spawns it as a local subprocess. For remote servers, containers, or headless environments, you can tunnel the connection over SSH. No additional server component needed.

SSH Tunnel (Recommended)

The simplest approach: configure your AI client to run lean-ctx via SSH. The MCP protocol flows over SSH's stdin/stdout - no ports to open, no HTTP, no authentication to manage. SSH handles encryption and authentication natively.

1. Install lean-ctx on the remote server

SSH into your server and install lean-ctx:

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

2. Test the connection

Verify lean-ctx works over SSH. You can either forward the MCP server directly or tunnel the 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 your AI client

Point your AI client's MCP config to run lean-ctx via SSH. This works with Cursor, Claude Code, Windsurf, Pi, and any MCP-compatible client:

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

This tells the client to spawn ssh user@server "lean-ctx" instead of a local lean-ctx. The MCP protocol flows transparently over the SSH connection - stdin/stdout is tunneled automatically.

Port Forwarding (Dashboard)

If you want to access the lean-ctx dashboard (Observatory) from your local browser while lean-ctx runs on a remote server, use SSH port forwarding:

Persistent SSH config

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

Then connect and start the dashboard:

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

VS Code Remote SSH

If you use VS Code with the Remote - SSH extension, lean-ctx works automatically - the MCP server runs on the remote machine just like any other terminal command. Install lean-ctx on the remote, run lean-ctx setup, and it configures itself for the remote environment.

Docker / Containers

For containerized development, mount the lean-ctx binary and its data directory into your container:

# 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

For Docker Compose, add the volumes to your 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

Troubleshooting

Connection drops after idle time

SSH connections can timeout during long idle periods. Add keepalive settings:

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

Permission denied on remote

Ensure lean-ctx is in the remote user's PATH. If installed via cargo install, it's at ~/.cargo/bin/lean-ctx. Add export PATH="$HOME/.cargo/bin:$PATH" to the remote ~/.bashrc or ~/.zshrc.

Version mismatch between local and remote

The local AI client and remote lean-ctx should run the same version to avoid protocol issues. Keep both updated:

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

Run diagnostics on the remote

Use lean-ctx doctor on the remote server to verify the installation, shell hooks, and MCP configuration:

ssh user@server "lean-ctx doctor"