How to manage Claude Code MCP servers on macOS

What Claude Code is actually managing

An MCP entry tells Claude Code how to reach a server. It does not guarantee that a local runtime is installed, a remote endpoint is online, or your credentials work.

That distinction saves time when something breaks. There is the saved configuration, the local process or remote service behind it, and the Claude Code session trying to connect. A problem in any one of those places can make the server unavailable.

1. Pick a scope before you add anything

Claude Code has three MCP scopes:

• Local loads the server only in the current project and keeps the entry private to your user account. It is the default.
• Project writes the entry to .mcp.json in the project root so it can be reviewed and shared through version control.
• User makes the server available across your projects on that Mac.

Local scope is a sensible place to test a server. Project scope works when the whole team needs the same setup. User scope is better for a personal tool you use everywhere.

2. Add the server with the Claude Code CLI

For a remote HTTP server, the command has this shape:

For a local stdio server, put the launch command after --:

The separator matters because it stops Claude Code from treating the server's arguments as its own flags. Some older remote services still use SSE, and Claude Code supports --transport sse for those. Follow the publisher's current instructions rather than choosing a transport from the server name.

WebSocket servers are the exception to this CLI-first workflow. Claude Code currently configures them through JSON or claude mcp add-json, not through the --transport flag.

3. Check the connection, not just the config

Start with:

An "Added" message only means Claude Code wrote the configuration. The list command reports a health state such as connected, needs authentication, or failed to connect.

Inside Claude Code, run /mcp. The panel shows server status and is where you can complete OAuth for supported remote servers. A project-scoped server may also wait for workspace trust and your approval before Claude Code connects to it.

4. Disable servers you do not need right now

You do not have to delete a server just to keep it out of one project. Open /mcp and toggle it off. Claude Code keeps the configuration but stops connecting to that server in the project.

This is worth doing. Fewer active servers means fewer processes to start, fewer connections to debug, and fewer tools available in the session.

Troubleshooting on a Mac

The command is not found

Run the stdio launch command directly in Terminal. If it fails there, install the required runtime or package first. If it only fails when launched from an app, check the PATH visible to that app. GUI apps on macOS do not always inherit the same shell environment as Terminal.

The process exits immediately

Run the exact command and arguments outside Claude Code so you can see its error output. Common causes include a missing package, a bad argument, or an environment variable that was never set.

The server needs authentication

Open /mcp in an interactive Claude Code session and complete the sign-in flow documented by the server. Non-interactive runs cannot open that OAuth panel for you.

The server is listed but unavailable

Read the status from claude mcp list or the server detail in /mcp. Recent Claude Code versions include the HTTP status or server error text for many failed remote connections. Fix the underlying command, endpoint, or credentials, then check again.

5. Remove old entries cleanly

If you no longer need the configuration, remove the named server through Claude Code:

Review the resulting diff when the server lives in project scope. Removing a shared entry changes the setup for everyone who uses that .mcp.json.

When a menu bar app is more convenient

The CLI is Anthropic's documented interface for adding, listing, and removing MCP servers. It is still a lot of typing if you regularly switch server sets or need to restart Claude Code sessions after a config change.