Claude Code MCP Config: Files, Servers, and Setup

What MCP Does in Claude Code

MCP stands for Model Context Protocol. It lets Claude Code connect to outside tools and services, such as local files or GitHub. To find the right settings, first tell Claude Code configuration apart from Claude Desktop configuration.

Claude Code stores MCP settings in a user-level file or a project-level file. On Windows, the user-level file is usually C:\Users\{username}\.claude.json. Replace {username} with your Windows account name. The file under AppData\Roaming\Claude is for Claude Desktop, not the usual Claude Code setup.

Use the claude mcp command to add or inspect servers. This is often simpler than editing JSON by hand. It also helps avoid mistakes in braces, quotes, and command paths.

Where Claude Code Stores MCP Settings

Claude Code settings can apply to one project, your user account, or a managed setup. A project file applies when you work in that project. User settings can apply across your workspaces.

The project-level file is named .mcp.json and sits in the project root. The user-level settings are kept in ~/.claude.json. On Windows, that shorthand points to your home folder, such as C:\Users\Sam\.claude.json.

Do not confuse that path with Claude Desktop's file at C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json. If you are setting up Claude Desktop, use its file. For Claude Code, use the Claude Code command or its own settings files.

• Project: .mcp.json in the project's top folder
• User: ~/.claude.json in your home folder
• Managed: Set by an organization, where available

Claude Code's scope rules and setup steps are covered in Anthropic's Claude Code MCP documentation. Check it if a release changes a command or setting.

How to Set Up an MCP Server

Before adding a server, check its setup notes. Some servers need Node.js and run through npx. Others use a local program, a container, or a web address. You need the right command and any required arguments.

Open a terminal in the project where you want to use the server. Add a local server with a command like this:

claude mcp add --scope project files -- npx -y @modelcontextprotocol/server-filesystem /path/to/folder

Replace /path/to/folder with the folder the server may access. On Windows, use a real folder path, such as C:\Users\Sam\Documents\work. Follow the server's own setup guide for the right package name and arguments.

The --scope project option saves the server for that project. Use --scope user to make it available across projects. The words after -- are the command Claude Code runs. Keep that command's location valid on your computer.

To add a server that uses a web address, use the HTTP transport option supported by your installed Claude Code version. Then give it the server's URL and any needed sign-in details. Run claude mcp list to check the saved servers.

Add, Check, and Remove Servers

Claude Code can connect to different kinds of MCP servers. A filesystem server can grant access to chosen folders. A GitHub server can expose repository tools. The server's features depend on its software and the access you grant.

Use the command line to see what is set up and to remove a server you no longer need. These commands help you check the connection without hunting through several files.

• List servers: claude mcp list
• View a server: claude mcp get files
• Remove a server: claude mcp remove files

Replace files with the server name you chose. If the server does not show up in a project, check its scope and the folder where you ran the add command.

You can also edit .mcp.json directly. A basic local server entry has a server name, a command, and an argument list. Keep valid JSON syntax, and use full paths when your system cannot find a command through its normal search path.

Fix Common MCP Connection Problems

When a server will not connect, first check that its command works outside Claude Code. Run the command in a terminal from the same account. If it fails there, fix the install or path before changing Claude Code settings.

Next, check the file location and scope. A project server should be in the project's .mcp.json file or added while working in that project. A user server should use the user scope. On Windows, verify that you edited the Claude Code file, not Claude Desktop's AppData file.

Bad JSON can stop Claude Code from reading a project file. Check for missing commas, unmatched braces, or quotes that are not escaped. Also confirm that the command points to an installed program and that your account can run it.

If the server needs a sign-in token, confirm that the token is still valid and that the server can read it. After fixing a setting, restart the session or reconnect the server. Test one change at a time so you can spot the cause.

Keep MCP Settings Safe and Manageable

Start with only the servers you need. Each active server can add tools and access paths, so a small setup is easier to review. Add another server only when a task calls for it.

Grant the smallest access that still lets the server do its job. For a file server, choose a work folder instead of your whole home directory. Remove old entries when a project or service is no longer in use.

Do not paste private tokens into a shared project file. Use environment variables or a secure secret store when the server supports them. Keep credentials out of version control, and review project changes before sharing them.

Keep Claude Code, Node.js, and each server package up to date. Updates can fix connection faults and security bugs. After an update, run claude mcp list and test any key server again.