MCP on Windows: check npx, JSON paths and WSL

When an MCP server launches in a terminal but not in an editor, inspect the execution environment first. Windows, WSL and a container are different places for programs and files. Record where the editor launches the server, which executable it uses and where the allowed folder resides. These three facts are more useful than changing multiple configuration files at once. The workflow below starts with a new test directory containing no existing documents.

Treat Windows and WSL as distinct environments

A Windows program does not automatically interpret a Linux path, and a Windows drive letter is not an ordinary absolute Linux path. Microsoft documents access to Windows drives from WSL through /mnt/. Verify the actual launch context before using such a path. For containers, the Docker guide explains how the host folder maps to its mounted destination.

Read a Windows Filesystem example

The example uses a mcpServers block and the Filesystem project’s documented Windows launch through cmd /c. Create C:\mcp-test before trying it and put only invented test data there. Adapt the file format to your client. MCP Roots supplied by the client can replace the directory list. Check list_allowed_directories before the first file operation. Limiting the directory does not automatically make the server read-only; explicitly select a read operation for your first check.

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\mcp-test"
      ]
    }
  }
}

Backslashes are doubled in JSON source. After parsing, C:\\mcp-test represents the path with a single separator. A directory containing spaces remains one element in args; additional quotation marks inside that value are not automatically needed. Do not confuse a JSON argument array with a fully assembled terminal command. If uncertain, check the syntax first with the configuration checker.

Check executable, arguments and access separately

1. Check that Node and npx can be located in the relevant environment. Record executable paths and versions without publishing your complete environment.

2. Verify the JSON block and argument order. Add just this server to the existing client configuration.

3. Start the server from the client and inspect its actual error. ENOENT before startup and a later denied folder operation are different problems.

4. Read a file created specifically for the test. Compare its contents, stop the server and record the path that was actually used.

Choose the next check from the observed failure

For a missing executable, use the ENOENT guide. If the process starts but tools or files are absent, avoid reinstalling without a diagnosis. Compare directory, process user and server arguments with the successful terminal attempt. The Filesystem guide explains access boundaries. A successful read on one machine does not validate a WSL setup or a colleague’s environment.

Must every program start through cmd?

No. This example covers the documented npx launch on Windows. Do not apply the wrapper indiscriminately to other programs.

Is a Linux path correct on Windows?

Only when the process runs in the corresponding environment. Determine who launches the server and where the directory exists.

Does valid JSON establish a working setup?

No. Syntax, process startup and file operations are three separate checks with distinct outcomes.

Should I immediately allow my documents folder?

A dedicated folder with invented data makes the first test easier to bound and clean up afterwards.

Provider documentation checked on 1 October 2026. Verification workflows are editorial suggestions.

1. MCP Filesystem: Windows configuration
   Show retrieval command

   curl -s https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem
2. Microsoft: WSL filesystems
   Show retrieval command

   curl -s https://learn.microsoft.com/en-us/windows/wsl/filesystems
3. Node.js: child processes on Windows
   Show retrieval command

   curl -s https://nodejs.org/api/child_process.html#spawning-bat-and-cmd-files-on-windows

All posts