Adding an MCP server to Claude Code is a one-line command once you know the shape of it. The friction is rarely the command itself — it’s choosing the right scope and, on native Windows, getting npx-based servers to actually launch. This guide covers both, plus how to verify a server connected and how to share servers with your team.
If you’re not sure what MCP is yet, start with the Model Context Protocol explained. Otherwise, open a terminal and let’s wire one up.
Before you start
Prerequisites
- Claude Code installed and working (you can run claude).
- Node.js available, since many servers launch via npx.
- Decided whether you're running in Windows PowerShell or WSL.
- Any API keys the server needs, kept in environment variables.
On Windows you have a choice of environments. If you want the Linux-style toolchain, the WSL2 install guide gets you there. The MCP commands are identical in both; the differences show up only in how commands are spawned and how paths are written.
The basic command
You register a server with claude mcp add. The pattern is a name, then --, then the command that starts the server:
claude mcp add <name> -- <command> [args...]A real example using the filesystem server over npx:
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dirThe part after -- is exactly what Claude Code will run to launch the server as a local subprocess over stdio. Everything before -- is configuration for Claude Code itself, like the scope flag below.
Choosing a scope
Scope decides who can see the server and where it’s stored. This is the setting people most often get wrong.
MCP server scopes
| Scope | Who sees it |
|---|---|
| local | Just you, this project (default) |
| project | Everyone on the project |
| user | Just you, all projects |
Set the scope with --scope:
claude mcp add github --scope user -- npx -y @modelcontextprotocol/server-githubUse local while you experiment. Move to project once a server is part of how the codebase works, so teammates get it automatically. Reserve user for personal utilities you want in every repo without committing anything.
Project scope and .mcp.json
When you add a server with --scope project, Claude Code writes it to a .mcp.json file at the project root. Commit that file and anyone who clones the repo inherits the same servers. A trimmed example:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"]
}
}
}Verifying the server connected
Start Claude Code and run the /mcp slash command:
/mcpIt lists each configured server, its connection status, and the tools it exposes. If a server shows as failed or disconnected, that’s your signal something in the launch command is wrong — usually a bad path, a missing package, or, on Windows, the wrapper issue below.
From the terminal you can also inspect configuration without launching a session:
claude mcp list
claude mcp remove <name>The Windows npx gotcha
This trips up nearly everyone running Claude Code on native Windows. Tools installed by npm — including npx — are typically .cmd shim files, not real executables. When Claude Code tries to spawn npx directly, Windows may refuse to run the shim the same way Linux runs a binary, and the server fails to start.
The fix is to launch through the command interpreter using cmd /c:
claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Users\YourName\projectThe cmd /c prefix tells Windows to run npx through cmd.exe, which knows how to resolve the .cmd shim. If you see a server that connects fine in WSL but fails on Windows with a spawn error, this wrapper is almost always the cure.
A couple of related Windows notes:
- Use Windows-style paths in Windows commands (
C:\Users\YourName\...) and Linux paths inside WSL (/home/you/...). Mixing them is a common cause of “directory not found” failures. - Reopen the terminal after installing Node so the updated PATH is picked up. A stale PATH makes
npxlook missing when it isn’t.
A clean end-to-end example
Putting it together on Windows, adding the filesystem server at user scope so it’s available everywhere:
claude mcp add filesystem --scope user -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Users\YourName\codeThen verify:
/mcpThe same thing in WSL drops the wrapper and uses a Linux path:
claude mcp add filesystem --scope user -- npx -y @modelcontextprotocol/server-filesystem /home/you/codeWrapping up
The mechanics are simple: claude mcp add <name> -- <command>, pick a scope, verify with /mcp. The two things that actually cause grief are choosing the wrong scope — local when you meant project, or vice versa — and the cmd /c npx wrapper on native Windows. Get those right and servers connect on the first try.
Once you’ve got servers connecting, browse the best MCP servers for Claude Code to decide what to add, or learn the internals by building your own MCP server.
