How to add an MCP server to Claude Code, and make it stick

Claude Code adds MCP servers from the command line, with one command, and it remembers them for you. The part that catches people out is not the command. It is the scope: by default a server you add is only available in the folder you added it from, so it seems to vanish the moment you open another project. Muse, a $29 Mac library for saved pictures, links and notes, is the worked example at the end: its built-in MCP server needs one command at user scope.

Everything below follows Anthropic's Claude Code MCP documentation, and we ran each command on a Mac to check it.

How do I add an MCP server to Claude Code?

Run claude mcp add in Terminal, followed by a name, two dashes, and the command that starts the server:

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

The two dashes matter. Everything before them is an option for Claude Code; everything after them is passed to the server exactly as written. A server that runs through npx looks like this:

claude mcp add airtable -- npx -y airtable-mcp-server

If a server needs an API key, pass it with --env (or -e), and put it after the name:

claude mcp add airtable --env AIRTABLE_API_KEY=YOUR_KEY -- npx -y airtable-mcp-server

For a server that lives on the internet rather than on your Mac, use --transport http and give its address instead of a command.

Which scope should I use: local, project or user?

This is the decision that decides whether a server is there tomorrow. Claude Code has three scopes:

• Local, the default. The server works only in the folder you ran the command from, and only for you. It is stored in ~/.claude.json.
• User. The server works in every project on your Mac. Also stored in ~/.claude.json. Add --scope user (or -s user).
• Project. The server is written to a .mcp.json file in the project folder, so anyone who clones the project gets it too. Add --scope project.

A rule of thumb: tools that belong to you, such as your notes, your library or your calendar, go in user scope. Tools that belong to the codebase, such as a database the team shares, go in project scope. Local scope suits a quick experiment.

What goes in a .mcp.json file?

Project scope writes a file you can also edit by hand. It uses the same shape as Claude Desktop's config, one mcpServers section with a named entry per server:

{
  "mcpServers": {
    "muse": {
      "command": "/Applications/Muse.app/Contents/MacOS/muse-mcp"
    }
  }
}

Commit it with the project and teammates get the same servers. Because a project file could start any program, Claude Code asks you to approve project-scoped servers before it uses them.

If you already have a server's JSON and would rather not translate it into a command, claude mcp add-json takes it directly:

claude mcp add-json --scope user muse '{"type":"stdio","command":"/Applications/Muse.app/Contents/MacOS/muse-mcp"}'

How do I check, fix or remove a server?

• claude mcp list shows every server Claude Code knows about and whether it connected.
• claude mcp get <name> shows one server's details, including its scope.
• claude mcp remove <name> removes it.
• Inside a session, type /mcp to see each server's status and its tools.

If you set servers up in Claude Desktop first, claude mcp add-from-claude-desktop copies them across, so you do not have to add each one twice.

When a server shows as failed, run its command on its own in Terminal. A missing program, a wrong path or a missing key usually announces itself there in one line. Paths should be full ones, starting from /.

A worked example: giving Claude Code your library

Claude Code is not only for code. Pointed at the right server, it is a capable assistant for tidying things up, and a library of saved pictures and links is a good example. Muse includes an MCP server from version 1.0.40. Turn on Allow AI Apps in Muse's Settings > Intelligence, then add it once for every project:

claude mcp add --scope user muse -- /Applications/Muse.app/Contents/MacOS/muse-mcp

There is a shortcut, too. Click Copy Setup in Muse, paste the result into a Claude Code chat and ask Claude to add Muse; it will run the command for you. After that you can ask things like "sort my Inbox into the right collections" or "find the link I saved about standing desks", and Claude works through Muse's own actions to do it. Anything it removes goes to Muse's Trash, and before the first change an AI app makes each day, Muse saves a copy of your library you can go back to. There is more on the Connect AI Apps guide.