リモート設定 — LeanCTX Docs

lean-ctx は stdio MCP サーバーとして動作し、AI クライアントがローカルのサブプロセスとして起動します。リモートサーバー、コンテナ、ヘッドレス環境では、接続を SSH 上でトンネルできます。追加のサーバーコンポーネントは不要です。

SSH トンネル（推奨）

最も簡単な方法：AI クライアントを SSH 経由で lean-ctx を実行するように設定します。MCP プロトコルは SSH の stdin/stdout を通って流れるため、ポート開放・HTTP・認証管理は不要です。SSH が暗号化と認証をネイティブに処理します。

1. リモートサーバーに lean-ctx をインストール

SSH でサーバーに接続し、lean-ctx をインストールします：

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

2. 接続をテスト

SSH 経由で lean-ctx が動作することを確認します。MCP サーバーをそのまま実行するか、ダッシュボードをトンネルできます：

# 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. AI クライアントを設定

AI クライアントの MCP 設定を、SSH 経由で lean-ctx を起動するように設定します。Cursor、Claude Code、Windsurf、その他 MCP 対応クライアントで動作します：

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

これによりクライアントはローカルの lean-ctx ではなく ssh user@server "lean-ctx" を起動します。MCP プロトコルは SSH 接続上で透過的に流れ、stdin/stdout は自動的にトンネルされます。

ポートフォワーディング（ダッシュボード）

lean-ctx をリモートで実行しつつ、ローカルブラウザから lean-ctx dashboard（Observatory）にアクセスしたい場合は、SSH のポートフォワーディングを使用します：

永続的な SSH 設定

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

その後、接続してダッシュボードを起動します：

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

VS Code Remote SSH

VS Code の Remote - SSH 拡張を使っている場合、lean-ctx は自動的に動作します。MCP サーバーは他のターミナルコマンドと同様にリモートマシン上で実行されます。リモートに lean-ctx をインストールし、lean-ctx setup を実行すると、リモート環境向けに設定されます。

Docker / コンテナ

コンテナ開発では、lean-ctx バイナリとデータディレクトリをコンテナにマウントします：

# 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

Docker Compose の場合は、サービスにボリュームを追加します：

# 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

トラブルシューティング

アイドル後に接続が切れる

SSH 接続は長時間アイドルだとタイムアウトすることがあります。keepalive 設定を追加してください：

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

リモートで Permission denied

リモートユーザーの PATH に lean-ctx が含まれていることを確認してください。cargo install の場合、~/.cargo/bin/lean-ctx にあります。リモートの ~/.bashrc か ~/.zshrc に export PATH=\"$HOME/.cargo/bin:$PATH\" を追加します。

ローカルとリモートのバージョン不一致

プロトコル問題を避けるため、ローカルの AI クライアントとリモートの lean-ctx は同じバージョンを使用してください。両方を最新に保ちます：

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

リモートで診断を実行

リモートサーバーで lean-ctx doctor を実行し、インストール、シェルフック、MCP 設定を確認します：

ssh user@server "lean-ctx doctor"