VSCode + asdf環境でMCPサーバーが Connection closed となる問題と解決策

VSCodeでMCP (Model Context Protocol) を利用する拡張機能(Cline）を使用する際、asdf でバージョン管理されたツールをMCPサーバーとして起動しようとすると MCP error -32000: Connection closed エラーが発生することがありました。本記事ではその原因と対策をまとめます。

環境

• Linux (Debian)
• asdf v0.17.0 (または類似バージョン)
• VSCode
• MCPを利用するVSCode拡張機能

問題の概要

VSCode拡張機能がMCPサーバープロセスを起動しようとすると、接続できずに MCP error -32000: Connection closed が出力パネルに表示される。

原因の特定

1. ターミナルからの手動実行: MCPサーバーコマンドはターミナルから直接実行すると正常に起動。
   ASDF_NODEJS_VERSION="vXX.YY.Z" /path/to/.asdf/shims/npx -y @modelcontextprotocol/server-filesystem /path/to/dir1 /path/to/dir2

2. VSCodeタスクランナーでの実行: VSCodeのタスクで同コマンドを実行すると exec: asdf: 見つかりません エラーが発生。

   • これは、asdf の shims スクリプトが内部で asdf コマンドを呼び出す際、VSCodeの実行環境では asdf へのパスが通っていないためと判明。拡張機能によるサーバー起動時も同様の問題が発生していると推測。

解決策: VSCode settings.json の設定

MCPサーバー設定を以下のように変更します。

設定のポイント:

• command: asdf 本体へのフルパスを指定。
• args: asdf exec <tool_command> ... 形式で実行。
• env.PATH: asdf コマンド本体があるディレクトリへのパスを追加。
• env.HOME: HOME 環境変数を明示的に設定。
• env.ASDF_TOOL_VERSION: (必要に応じて) asdf が使用するツールのバージョンを指定 (例: ASDF_NODEJS_VERSION)。

{
  "mcpServers": {
    "filesystem": { // 例: filesystemサーバー
      "disabled": false,
      "timeout": 120,
      "command": "/home/user/.local/bin/asdf", // asdf本体のフルパス (例)
      "args": [
        "exec", // asdf exec を使用
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/your/project1" // 操作対象ディレクトリ
      ],
      "env": {
        "ASDF_NODEJS_VERSION": "v22.16.0", // 使用するNode.jsのバージョン
        "HOME": "/home/user",         // HOMEディレクトリ (例)
        "PATH": "${env:PATH}:/home/user/.local/bin" // asdfへのパスを追加 (例)
      },
      "transportType": "stdio"
    }
    // 他のasdf管理ツールを使用するサーバーも同様
  }
}

注意: 上記設定例の /home/user/ や /path/to/... はご自身の環境に合わせてください。

なぜ解決するのか

• asdf exec は、選択されたバージョンのツールを適切な環境で実行します。
• VSCodeのプロセス起動時はシェルの初期設定が完全に読み込まれないため、PATH や HOME を明示的に指定する必要があります。

これで、VSCode拡張機能から asdf 管理下のツールをMCPサーバーとして安定起動できるようになります。