How to add an MCP server to Claude Code

Where Claude Code keeps its MCP config

Project (committed)

.mcp.json

User (all projects)

~/.claude.json

Add the server from the terminal

Claude Code has a command for this, so there is no file to find. Everything after the double dash is the command Claude Code will run to start the server.

The double dash matters: it stops Claude Code from trying to parse the server's own flags as its own.

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

Choose the right scope

Scope decides who gets the server. local keeps it to you in this project and is the default. project writes it to .mcp.json in the repository, so everyone who checks out the code gets it. user makes it available in all your projects.

Use project for servers the whole team needs and user for personal tooling. Never use project for a server that carries your own credentials — the config is committed, and the token goes with it.

claude mcp add --scope project github -- npx -y @modelcontextprotocol/server-github
claude mcp add --scope user linear -- npx -y mcp-linear

Check what is connected

claude mcp list shows every configured server and whether it connected. Inside a session, the /mcp command shows the same thing plus the tools each server exposes.

If a server is listed but has no tools, it started and then failed its handshake — usually a missing credential rather than a bad command.

claude mcp list

If the server does not connect

Check the JSON parses. A trailing comma is the single most common cause of a server that silently never appears — the client cannot read the file, so it falls back to no servers rather than reporting an error.

Use an absolute path to the command. Clients do not always launch with your shell's PATH, so `npx` may resolve interactively and fail on startup. `which npx` gives you the full path to paste in.

Check the server actually runs on its own. Paste the same command into a terminal: if it exits immediately, the problem is the server or its credentials, not the client config.

Frequently asked questions

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

local is you, in this project only, and is the default. project writes the server to .mcp.json so it is shared with everyone who clones the repository. user makes the server available across all of your own projects.

How do I see which MCP servers Claude Code has loaded?

Run claude mcp list in the terminal, or type /mcp inside a session. Both show the configured servers; /mcp also lists the tools each one exposes.

Should I commit .mcp.json?

Yes for servers the whole team needs, and only when no credentials are in it. Keep anything holding a token in user or local scope so it never reaches the repository.