Skip to content

README: ambiguous WSL guidance - using "wsl" in mcp.json can break Remote-WSL (ENOENT) #190

@torumakabe

Description

@torumakabe

Summary: The README currently suggests setting "command": "wsl" for VS Code running inside WSL. This is ambiguous and can be misleading. When VS Code is opened inside WSL (Remote - WSL), using "wsl" in mcp.json will generally not work: "wsl" is a Windows-side launcher and is not available/meaningful from inside the WSL extension host, which leads to spawn/ENOENT errors and MCP startup failure.

Steps to reproduce:

  1. Open VS Code inside a WSL distro (Remote - WSL).
  2. Add a user-level mcp.json entry that uses "command": "wsl" and args pointing to a WSL path (e.g., "/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp").
  3. Start the MCP server. The server fails to spawn and logs errors like "Server exited before responding to initialize request."

Expected behavior: The README should clearly distinguish the two different contexts and provide correct examples for both:

  • Windows host VS Code (extension host on Windows): when invoking a WSL binary from Windows, use "command": "wsl".
  • VS Code running in WSL (Remote - WSL; extension host on Linux): do NOT use "wsl". Call the Linux binary directly or use a shell wrapper such as "bash -c".

Suggested fix (concise):

  • Update the WSL note to explicitly separate the two contexts (Windows host vs Remote-WSL) and give sample configurations for each.
  • Add a short Troubleshooting note for ENOENT and recommend checking whether VS Code is running on Windows or inside WSL.

Windows (VS Code on Windows — invoke WSL binary via wsl):

{
  "servers": {
    "aks-mcp": {
      "type": "stdio",
      "command": "wsl",
      "args": [
        "--",
        "/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}

WSL (VS Code running inside WSL — call bash or binary directly):

{
  "servers": {
    "aks-mcp": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp --transport stdio"
      ]
    }
  }
}

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions