⛳

VSCodeでMCPの起動に失敗する「エラー spawn uvx ENOENT」

に公開
VS Code
Model Context Protocol
GitHub Copilot
tech

事象

エラー内容

2025-11-16 13:16:51.493 [info] サーバー awslabs-aws-documentation-mcp-server を起動しています
2025-11-16 13:16:51.495 [info] 接続状態: エラー spawn uvx ENOENT

発生条件

  • VS Code 1.106.0 (2025年11月12日リリース) にアップデート後
  • mcp.json で MCP サーバーのコマンドを相対パス（uvx など）で指定している場合
  • macOS で Dock/Spotlight から VS Code を起動した場合

以前は動いていた

  • VS Code 1.105.x 以前では同じ設定で正常に動作していた

原因

1. 技術的な原因

ソースコード: src/vs/workbench/api/node/extHostMcpNode.ts

72行目:

const env = { ...process.env };

拡張ホストプロセスの環境変数をそのままコピー

78-80行目:

for (const [key, value] of Object.entries(launch.env)) {
    env[key] = value === null ? undefined : String(value);
}

mcp.json の env プロパティで明示的に指定された環境変数のみを追加

100-105行目:

child = spawn(executable, args, {
    stdio: 'pipe',
    cwd,
    env,  // ← 上で作成した env を使用
    shell,
});

この env を使って子プロセスを起動

2. 環境変数の継承チェーン

┌─────────────────────────────────────────────────────────────┐
│ VS Code (Electron)                                          │
│ PATH=/usr/bin:/bin:/usr/sbin:/sbin                         │
│ ※ GUI起動時、シェル設定を読み込まない                        │
└──────────────────┬──────────────────────────────────────────┘
                   │ spawn
                   ↓
┌─────────────────────────────────────────────────────────────┐
│ Extension Host (Node.js)                                    │
│ PATH=/usr/bin:/bin:/usr/sbin:/sbin                         │
│ ※ 親プロセスの環境変数を継承                                 │
└──────────────────┬──────────────────────────────────────────┘
                   │ process.env をコピー
                   ↓
┌─────────────────────────────────────────────────────────────┐
│ MCP Server Process                                          │
│ PATH=/usr/bin:/bin:/usr/sbin:/sbin                         │
│ ※ mcp.json の env で追加指定がない限り PATH は変わらない     │
│ ❌ /opt/homebrew/bin が含まれていない                        │
│ ❌ uvx が見つからない → spawn ENOENT                         │
└─────────────────────────────────────────────────────────────┘

3. なぜ v1.106.0 で問題が発生したか

v1.105.x 以前:

  • MCP の stdio サポートが未実装または異なる実装
  • 何らかの方法で PATH が補完されていた可能性

v1.106.0 (2025年11月12日):

  • MCP 機能の正式サポート・強化
    • 組織レベルでの MCP サーバーアクセス管理
    • ワークスペース設定への MCP サーバーインストール
    • 認証機能の強化 (CIMD, WWW-Authenticate)
  • セキュリティ強化の一環で、環境変数の扱いが厳格化
  • 明示的に指定された環境変数のみを使用する実装に変更

4. VS Code 拡張ホストについて

拡張ホストとは:

  • VS Code の拡張機能を実行する Node.js プロセス
  • VS Code 本体 (Electron) から spawn される
  • プロセス名: Code Helper (utility) または Code Helper (Plugin)

拡張ホストの PATH 問題:

  • macOS で Dock や Spotlight から起動したアプリはシェル設定（.zshrc, .bash_profile）を読み込まない
  • そのため、限定的な PATH しか持たない: /usr/bin:/bin:/usr/sbin:/sbin
  • Homebrew のパス /opt/homebrew/bin は含まれない
  • MCP サーバー起動時にこの PATH がそのまま継承される

解決策

方法1: フルパス指定（推奨）✅

~/Library/Application Support/Code/User/mcp.json:

{
  "servers": {
    "awslabs-aws-documentation-mcp-server": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": {}
    }
  }
}

メリット:

  • ✅ 最も確実で安全
  • ✅ PATH に依存しない
  • ✅ 環境の違いによる問題が起きにくい
  • ✅ パフォーマンスが良い（PATH 検索不要）

方法2: env で PATH を指定

{
  "servers": {
    "awslabs-aws-documentation-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
      }
    }
  }
}

メリット:

  • ✅ コマンド名を変更せずに済む
  • ✅ 複数のコマンドで PATH を共有できる

デメリット:

  • ⚠️ 各サーバー設定で PATH を指定する必要がある
  • ⚠️ PATH が環境依存になりやすい

方法3: システムレベルでの PATH 設定（非推奨）❌

~/.MacOSX/environment.plist や launchctl setenv でシステム全体の PATH を設定する方法もありますが、以下の理由で推奨されません:

  • ❌ セキュリティリスク（全アプリに影響）
  • ❌ macOS バージョンアップで動作しなくなる可能性
  • ❌ 管理が複雑

実施した修正内容

修正ファイル: ~/Library/Application Support/Code/User/mcp.json

以下の4つの MCP サーバー設定で uvx のフルパスを指定しました:

  1. awslabs-terraform-mcp-server
  2. awslabs-aws-documentation-mcp-server
  3. awslabs.aws-pricing-mcp-server
  4. awslabs.aws-api-mcp-server

変更内容:

- "command": "uvx",
+ "command": "/opt/homebrew/bin/uvx",

次のステップ:
VS Code を再起動すると、MCP サーバーが正常に起動するようになります。

まとめ

項目 内容
原因 拡張ホストが process.env をコピーするため、GUI 起動時の限定的な PATH しか継承されない
トリガー v1.106.0 で MCP stdio サーバーの実装が正式化・厳格化された
影響範囲 Homebrew など、標準パス以外にインストールされたコマンドを使用する MCP サーバー
対策 フルパス指定または env で PATH を明示的に指定
根本要因 macOS の GUI アプリがシェル設定を読み込まない仕様 + セキュリティ強化

参考情報

VS Code リリース情報

関連する v1.106.0 の変更

  • MCP server access for your organization (組織レベルのアクセス管理)
  • Install MCP servers to workspace configuration (ワークスペース設定対応)
  • Authentication: Client ID Metadata Document authentication flow
  • Authentication: WWW-Authenticate scope step up

ソースコード

  • ファイル: src/vs/workbench/api/node/extHostMcpNode.ts
  • リポジトリ: https://github.com/microsoft/vscode
  • 重要な行: 72行目（環境変数のコピー）、100-105行目（spawn 呼び出し）

Discussion