Claude Code on the Mac

Written & tested for accuracy by a developer (not AI) · Updated June 2026

Add MCP Servers to Claude

How to add MCP servers to Claude Code with claude mcp add, and to Claude Desktop with connectors or configuration files.

Claude Code is Anthropic's AI coding tool. It runs in your terminal with the claude command, and in the Claude Desktop app's Code tab. MCP servers give it abilities it doesn't have on its own, such as reading web pages cleanly, looking up current documentation, or working with your team's tools. If MCP is new to you, start with MCP Servers on Mac, which explains what MCP servers are and how to choose them safely.

Here I show how to add, check, and remove MCP servers in Claude Code, and how to add them to Claude Desktop, which has its own settings.

Before you get started

I recommend using our free app to get Claude Code ready for MCP servers. It is a FREE Mac app that installs Claude Code, adds MCP servers you choose, and verifies Claude Code is working. It does the basic setup this guide covers, but easier and faster. Here are all the details about the app before you download. Then:

First steps to add MCP servers to Claude Code

First, check the macOS version. If you're running an older version, update macOS to the latest macOS version.

You'll need Claude Code installed. See Install Claude Code on Mac. I used Claude Code 2.1.278 for the commands on this page (October 2026).

Many local MCP servers start with the npx command, which comes with Node.js. Some need Node.js 20 or later, so install the current version with Homebrew:

$ brew install node

Some MCP servers written in Python start with the uvx command instead. For those, install uv.

Remote MCP servers need neither. Claude Code connects to them over the internet.

Understand local and remote MCP servers

Claude Code can use two kinds of MCP server.

A local MCP server runs on your Mac. Claude Code starts it with a command when a session begins and talks to it directly. The MCP documentation calls this the "stdio" transport. A local server runs with your permissions, so only add ones you trust.

A remote MCP server runs in the cloud. Claude Code connects to it with a web address. The documentation calls this the "HTTP" transport. Many remote servers ask you to sign in with your own account the first time. You may also see an older remote type called SSE. It is deprecated, and Claude Code now falls back to it automatically when a server needs it, so you can use --transport http for any remote server.

Add a remote MCP server

The claude mcp add command adds a server to Claude Code. For a remote server, give --transport http, a short name you choose, and the server's web address. This example adds Notion's official MCP server:

$ claude mcp add --transport http notion https://mcp.notion.com/mcp

If the server uses an API key, the server's instructions will tell you how to send it. Usually it goes in a header:

$ claude mcp add --transport http <name> <url> --header "Authorization: Bearer YOUR_API_KEY"

If the server asks you to sign in, start Claude Code, type /mcp, choose the server, and choose Authenticate. Your web browser opens so you can sign in to the service.

Add a local MCP server

For a local server, give --transport stdio, a name, then two dashes (--) and the command that starts the server. Everything after the two dashes goes to the server, not to Claude Code. This example adds Microsoft's Playwright server, which lets Claude Code control a web browser:

$ claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

The @latest at the end tells npx to check for the newest version of the server. Without a version, npx can keep running an old copy it saved earlier, even after the publisher fixes a bug.

To give a local server an API key, use --env to set an environment variable. Put another option between --env and the server's name, or Claude Code reads the name as a second variable:

$ claude mcp add --env API_KEY=YOUR_API_KEY --transport stdio <name> -- <command>

Choose a scope: local, project or user

Every MCP server has a scope, which decides where it works and who sees it. Add --scope (or -s) to the claude mcp add command to choose one:

  • local (the default) - the server works only in the project folder where you added it, and only for you. Claude Code saves it in ~/.claude.json under that folder's path.
  • project - the server works for everyone who works on the project. Claude Code saves it in a file named .mcp.json in the project folder, which you commit to Git.
  • user - the server works in every project on your Mac, only for you. Claude Code saves it in ~/.claude.json.

I recommend --scope user for servers you'll want everywhere, such as a documentation or web-reading server. Use --scope project for servers a whole team needs for one project.

Be careful with the names. "Local scope" has nothing to do with the .claude/settings.local.json file, and a local-scope server can be a remote server. If the same server name appears in more than one scope, Claude Code uses the local one first, then the project one, then the user one.

Share MCP servers with your team

A project-scope server lives in .mcp.json at the top of the project folder. Here is what the file looks like with one remote server:

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Anyone who opens the project in Claude Code gets the server, after Claude Code asks them to approve it. If you change your mind about an approval, run claude mcp reset-project-choices.

Never put an API key in .mcp.json, because the file goes into Git. Write a variable instead, such as ${API_KEY}, and each person sets the variable on their own Mac. Claude Code fills it in when it starts the server. For Claude Code in the terminal, set the variable in ~/.zprofile (see .zshrc or .zprofile). The Claude Desktop app is different: it takes only PATH and a few of Claude Code's own settings from your shell files. For the Code tab, open the environment menu in the prompt box, hover over Local, and click the gear icon to add the variable there.

Add a server from JSON

Some MCP servers give their setup as a block of JSON. Paste it with claude mcp add-json:

$ claude mcp add-json --scope user <name> '{"type":"http","url":"https://example.com/mcp"}'

Always include "type" for a server with a web address. Without it, Claude Code treats the entry as a local server and it fails.

List, check and remove MCP servers

To see every server and whether it works, run:

$ claude mcp list

Claude Code connects to each server and shows its status: "✔ Connected", "! Needs authentication", "✘ Failed to connect", or "⏸ Pending approval" for a project server you haven't approved yet. To see one server's details, run claude mcp get <name>.

Important: these commands show each server's full web address, and claude mcp get shows its headers too. If a server's API key is part of its address or its headers, the key appears on your screen. Don't paste this output into a chat, an issue, or a screenshot.

To remove a server, run:

$ claude mcp remove <name>

Add --scope user (or the scope you used) if Claude Code asks which one to remove. Removing a server also deletes its saved sign-in.

Get MCP servers from Claude Code plugins

Plugins are packages that add skills, commands, and MCP servers to Claude Code in one step. Type /plugin in Claude Code and choose Discover to browse Anthropic's plugin directory. Many plugins include MCP servers, and those servers start automatically when you turn the plugin on. Anthropic says it doesn't control the MCP servers inside plugins, so check who publishes a plugin before you install it, just as you would for a server.

Manage MCP servers with /mcp inside Claude Code

Inside a Claude Code session, type /mcp. You'll see each server's status and how many tools it offers. From there you can sign in to a server, sign out, turn a server on or off for the current project, reconnect a server that dropped, and approve project servers. In Claude Code 2.1.284 and later, /mcp reconnect all reconnects every server at once.

Use MCP tools, resources and prompts

Once a server is connected, you don't need to call its tools yourself. Ask Claude Code for what you want, and it picks the tool that fits. The first time it uses a tool, Claude Code asks your permission.

If you tell Claude Code not to ask again, it remembers your answer only for the current project. To allow every tool from a server in all your projects, add mcp__ and the server's name to the allow list in ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__playwright"]
  }
}

Some servers also offer resources and prompts:

  • Resources - type @ in a prompt to see what servers offer, then pick one to include it. For example, @github:issue://123 brings in an issue from GitHub.
  • Prompts - a server's prompts appear in the / menu as the server's name and the prompt's name, such as /<server>:<prompt>.

Every server's tool descriptions use some of Claude Code's context (its working memory for the conversation). Claude Code keeps this small with tool search, which is on by default: it loads only the tools' names at the start and loads a tool's full description when it needs it. If a server sends back a large result, Claude Code warns you above 10,000 tokens and cuts the result off at 25,000 tokens. You can raise the limit by starting Claude Code with the MAX_MCP_OUTPUT_TOKENS variable, such as MAX_MCP_OUTPUT_TOKENS=50000 claude.

Add MCP servers to Claude Desktop

Claude Desktop has three ways to add MCP servers to its Chat tab. Its Code tab is Claude Code, so it already uses the servers you added with claude mcp add.

Add a connector

A connector is a remote MCP server that you add in Claude's settings. Open Settings > Connectors in Claude Desktop to browse Anthropic's directory of connectors and connect one with your own sign-in. To add a server that isn't in the directory, choose Add custom connector and enter its web address. Every Claude plan can add custom connectors, but the free plan allows only one.

A custom connector connects from Anthropic's computers, not from your Mac, so it works only with servers on the public internet. Connectors you add on the claude.ai website also appear in Claude Code when you sign in to Claude Code with the same Claude subscription. They don't appear if Claude Code uses an API key.

Install a desktop extension

Anthropic no longer accepts new extensions in its directory. New local servers now come packaged in plugins, so extensions are no longer common.

A desktop extension is a local MCP server packaged as a single file ending in .mcpb (older ones end in .dxt). Open Settings > Extensions and choose Browse extensions, or install a file you downloaded from the Advanced settings section. Extensions include their own copy of Node.js, so you don't need to install it.

Edit claude_desktop_config.json

You can also add a local server to Claude Desktop by editing its configuration file:

~/Library/Application Support/Claude/claude_desktop_config.json

To find the file, choose Claude > Settings > Developer, then click Edit Config. Claude Desktop creates the file if it doesn't exist.

Important: quit Claude Desktop completely (Claude > Quit Claude) before you change the file. Closing the window isn't enough. The running app keeps its own copy of the file and writes that copy back when it saves one of its settings, which can wipe out your changes. Keep a backup copy of the file, because Claude Desktop sometimes overwrites it anyway.

Open the file in a code editor and add your server under mcpServers. This example adds the MCP project's filesystem server, which lets Claude read files in one folder:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@latest", "/Users/yourname/Desktop"]
    }
  }
}

Use full paths, starting with /Users/, not ~. Save the file, then open Claude Desktop again.

Share MCP servers between Claude Desktop and Claude Code

Claude Code in the terminal doesn't read claude_desktop_config.json. To copy servers from Claude Desktop into Claude Code, run:

$ claude mcp add-from-claude-desktop

Claude Code asks which servers to import. Add --scope user to make them work in every project.

Going the other way is automatic. Claude Desktop's Code tab loads the servers in ~/.claude.json and .mcp.json, and it also loads the ones in claude_desktop_config.json. If the same name appears in both, the Code tab uses the version in claude_desktop_config.json.

Claude Code on the web is different. A cloud session on claude.ai only gets the servers in a project's committed .mcp.json file and your claude.ai connectors. Servers you added with local or user scope stay on your Mac.

Fix an MCP server that won't connect

When claude mcp list shows "✘ Failed to connect", try these fixes:

  • Run the server's command yourself. For a local server, run its command (such as npx -y @playwright/mcp@latest) in a terminal application and read the error.
  • Give the full path to the command. An error such as spawn npx ENOENT means the app couldn't find the command. Run which npx to find its full path (on a Mac with Apple Silicon, Homebrew puts it at /opt/homebrew/bin/npx), and use that path in place of npx.
  • Give a slow server more time. The first npx run downloads the server, which can take longer than Claude Code waits. Start Claude Code with a longer limit, in milliseconds: MCP_TIMEOUT=60000 claude.
  • Sign in again. For "! Needs authentication", type /mcp in Claude Code, choose the server, and sign in.
  • Use the publisher's plugin or client ID. If sign-in fails with "Incompatible auth server: does not support dynamic client registration", the server needs a client ID that Claude Code can't get on its own. Install the publisher's Claude Code plugin if it offers one, or follow its instructions to add the client ID.
  • Read Claude Desktop's logs. Claude Desktop writes each server's errors to ~/Library/Logs/Claude/. Watch them with:
$ tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Use MCP servers safely

An MCP server can read what you connect it to, and a local server runs with your permissions. Add servers from publishers you trust, preferably the company that runs the service, and give each one the fewest permissions it needs. Be wary of servers that read outside content such as web pages or email, which can carry hidden instructions to Claude. See MCP Servers on Mac for more on choosing servers safely.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.