How to set up an MCP server in Claude Code on Windows

TL;DR: To set up an MCP server in Claude Code on Windows, use claude mcp add for remote HTTP servers as-is, and wrap any stdio server that runs through npx with cmd /c.

The wrapper is the one Windows-specific detail that breaks most setups: without it, npx fails to spawn and the server appears in claude mcp list but never connects.

This guide covers the three server types (HTTP, SSE, stdio), the three configuration scopes, the exact commands that work in PowerShell and Git Bash, and the errors you will hit if you skip the wrapper.

Prerequisites

Before adding any server, confirm the following on your machine:

• Claude Code installed. Run claude --version. The MCP scope rename (local replacing project, user replacing global) landed in newer versions; older blog posts use the old names.
• Node.js 18 or newer on PATH if you plan to run any stdio server that uses npx. Run node --version and npx --version in a fresh terminal. If npx is not found, fix the PATH before continuing - no MCP wrapper compensates for a missing Node install.
• A working terminal. Either Windows PowerShell, the new Windows Terminal, or Git Bash. WSL is not required for Claude Code on Windows; the native install works.

Pick a scope before you add a server

Claude Code stores MCP servers at one of three scopes. Choosing the wrong one is the second most common reason a server "disappears" between sessions or projects.

Scope	Loads in	Shared with team	Stored in
local (default)	Current project only	No	~/.claude.json
project	Current project only	Yes, via Git	.mcp.json in project root
user	All your projects	No	~/.claude.json

Use project when the server is part of the codebase contract (everyone on the team needs the same database or issue tracker). Use user for personal utilities you want everywhere. Use local (the default) for anything experimental or anything carrying credentials you do not want committed.

Option 1: Add a remote HTTP server (no Windows-specific quirks)

Remote servers - Stripe, Notion, Sentry, GitHub - run on someone else's infrastructure. Claude Code talks to them over HTTP, so Windows behaves identically to macOS or Linux. This is the path of least resistance.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Then start Claude Code and run /mcp to authenticate via OAuth in your browser. The server appears as connected in claude mcp list once the handshake completes. If a remote server disconnects mid-session, Claude Code retries with exponential backoff up to five attempts.

For servers that authenticate with a token instead of OAuth, pass it as a header. GitHub's remote MCP server is the canonical example:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ ^
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

The ^ is cmd.exe's line continuation (and works when you invoke claude from a cmd-style command line); in PowerShell scripts use the backtick (`); in Git Bash use \. Paste the command on one line if either feels awkward.

Option 2: Add a local stdio server (where Windows differs)

Stdio servers run as a child process on your machine. Most are distributed as npm packages and started with npx. On macOS and Linux, npx resolves to a shell-callable binary; on Windows it resolves to npx.cmd, which the Node child-process spawn used inside Claude Code does not invoke directly. The result is a silent failure or a spawn npx ENOENT error in the MCP log.

The fix documented in SuperClaude Framework issue #390 is to wrap the call with cmd /c. There are two ways to apply it.

Method A: through the CLI

The claude mcp add syntax for stdio servers is:

claude mcp add [options] <name> -- <command> [args...]

All flags (--transport, --env, --scope) come before the server name. The double-dash -- separates the name from the command Claude Code will spawn. Getting this order wrong is the most common subtle failure: flags placed after the name are passed to the MCP server, not to Claude Code, and the configuration looks correct but the server never starts.

To add the filesystem server on Windows:

claude mcp add --transport stdio filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Users\you\projects

Note the four pieces after --: the literal command (cmd), the /c flag telling cmd to run and exit, the actual binary (npx), and its arguments.

Method B: edit .mcp.json directly

For project scope, or when you want the configuration in version control, edit .mcp.json at the project root. The same wrapper applies:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:/Users/you/projects"]
    },
    "sequential-thinking": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Use forward slashes in path arguments. Windows accepts them, and JSON does not need backslash escaping. Restart Claude Code after editing the file.

Verify the server is connected

Three checks, in order:

1. List configured servers. Outside Claude Code, run claude mcp list. The server should appear with the command you registered.
2. Check live status. Inside Claude Code, type /mcp. Servers show as connected, pending, or failed. A failed stdio server means the spawn errored - usually the cmd /c wrapper is missing or npx is not on PATH.
3. Use a tool. Ask Claude to do something the server enables ("list files in my projects directory" for the filesystem server). If the server is wired correctly but the tool errors, the problem is permissions or arguments, not the connection.

If a stdio server stops mid-session, it will not auto-reconnect - that retry behaviour applies only to HTTP and SSE transports. Restart Claude Code to bring it back.

Common errors and what they mean

• spawn npx ENOENT - npx not found by the spawn call. Add the cmd /c wrapper, or confirm Node is on the PATH visible to Claude Code (open a fresh terminal and check).
• Server failed to start after the first OAuth flow - the handshake timed out. Set MCP_TIMEOUT=10000 in your environment before launching Claude Code to give it 10 seconds.
• This project's MCP servers must be approved - you added a project-scoped server from .mcp.json; Claude Code requires explicit approval the first time. Approve it at the prompt, or run claude mcp reset-project-choices to start over.
• Server shows in list but never appears under /mcp - flag ordering is wrong. Re-run claude mcp add with all options before the name and the command after --.

FAQ

Why does npx fail on Windows in Claude Code MCP servers?

Because npx on Windows is npx.cmd, a batch script that the Node child-process spawn used by Claude Code does not invoke as an executable. Wrapping the call with cmd /c hands the script to the shell that knows how to run it.

Where is the MCP config file stored on Windows?

Local and user-scoped servers live in %USERPROFILE%\.claude.json (typically C:\Users\you\.claude.json). Project-scoped servers live in .mcp.json at the root of the project where you ran claude mcp add --scope project.

What is the difference between local, project, and user scope?

local (default) loads the server only in the current project and keeps it private to you. project loads it only in the current project but shares the configuration via the committed .mcp.json. user loads it in every project for your account. When the same server name is defined at multiple scopes, local wins, then project, then user.

Do I need WSL to run MCP servers in Claude Code on Windows?

No. The native Windows install of Claude Code runs MCP servers directly. WSL is only useful if a specific server lacks a Windows build or you prefer a Linux toolchain for unrelated reasons.

How do I authenticate a remote MCP server that needs OAuth?

Add the server with claude mcp add --transport http <name> <url>, start Claude Code, and run /mcp. Pick the server from the list; Claude Code opens your browser to complete the OAuth flow and stores the resulting token under your user profile.