claude mcp add: Connecting MCP Servers to Claude Code

Published 11-11-2026. Last verified on 11-11-2026 with Claude Code 2.1.322, reviewed monthly.

Quick answer: what is the one command you need?

This guide is for developers and small technical teams who want to give Claude Code a new tool, such as a database, a design file or a browser, and need it working for the whole team without putting keys in the repo. The command is claude mcp add, and the part most people get wrong is the scope, not the syntax. For a server that runs on your machine:

claude mcp add memory -- npx -y @modelcontextprotocol/server-memory

For a remote server: claude mcp add --transport http <name> <url>. Add --scope project when the team should share it and --scope user when you want it in every project. Then run claude mcp list to see whether it connects. Everything on this page was run by us on 11-11-2026, and we quote the real output, including the five commands that failed.

How we tested every command on this page

Our method in three lines: run what is described, label vendor statements separately from what was observed, and name what could not be checked. The gate for this page is stricter: a command only goes in if we ran it and can paste the output.

The test session: Claude Code 2.1.322 installed from npm on Linux, a clean home directory, a fresh git repository, 11-11-2026. We ran 12 claude mcp add commands. 7 succeeded and 5 failed, and each failure is quoted in the section where it teaches something. We then ran list, get and remove.

Three things failed our gate and stay out or carry a label. We could not test add-from-claude-desktop, because it refuses to run on Linux. We have no connection result for remote HTTP servers, because our test sandbox blocks outbound traffic to those hosts, so a failed connection there says something about our network and nothing about the server. And we dropped the advice, common in ranking blogs, to wrap npx in cmd /c on Windows: it is not in the official docs and we did not test Windows.

We sell skills that Claude Code, Cursor, Codex CLI and Copilot load through one connection to Agensi (see the MCP setup guide), and we name a few of ours where they solve an MCP problem. No vendor paid to be listed.

What does claude mcp add do, and what is the syntax?

claude mcp add writes a server definition into a Claude Code config file, so that the next session can start that server and use its tools. It does not install the server itself; for a local server, the command you give (usually npx or uvx) does that when Claude Code first starts it.

The syntax from claude mcp add --help in version 2.1.322:

claude mcp add [options] <name> <commandOrUrl> [args...]

The options that matter in daily use are --transport (stdio, http or sse, default stdio), --scope (local, user or project, default local), --env for environment variables and --header for HTTP headers. For local servers, the double dash -- separates Claude's own options from the command that starts the server. Everything before -- belongs to Claude, everything after it belongs to the server. Our rule: put every flag before the server name, and the server command after --. That ordering avoids most of the errors in the troubleshooting section.

If you would rather paste a full definition, claude mcp add-json takes the name and a JSON object. We added an HTTP server with a header this way:

claude mcp add-json weather '{"type":"http","url":"https://api.weather.example/mcp","headers":{"Authorization":"Bearer test"}}'
Added http MCP server weather to local config

If you are new to the protocol itself, read our explainer on what MCP is first; this page assumes you already know which server you want.

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

Use local for experiments and anything with your own keys, project for tools the whole team needs, and user for personal tools you want in every repository. The scope decides which file gets the definition and who sees it. One add per scope, with the file each command reported:

The project scope is the one with consequences. The .mcp.json file it wrote was plain JSON, committed with the repo:

{
  "mcpServers": {
    "everything": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {}
    }
  }
}

Two rules follow from that. First, never put a token in .mcp.json: the Claude Code MCP docs support ${VAR} and ${VAR:-default} expansion in command, args, env, url and headers, so the file can reference a variable that each developer sets locally. Second, expect an approval step. The docs say Claude Code asks for approval in interactive sessions before it uses project servers from .mcp.json, and claude mcp list showed exactly that state: ⏸ Pending approval (run 'claude' to approve).

When the same name exists in more than one scope, the docs say Claude Code uses one definition from the highest-ranked source, in the order local, project, user, and does not merge fields. One observation we could not explain: with the same server name in project and user scope, and the project copy still unapproved, claude mcp get reported the user copy. Our reading is that an unapproved project server does not count yet; that is not confirmed.

Teams that standardize shared config across repositories will find setup and CI helpers in our DevOps and cloud skills. Before anyone commits a third-party server to .mcp.json, we would run a check on it first; Install Guard by its listing reviews a skill or MCP server config before your agent trusts it. Our MCP server security audit guide covers what to look for by hand.

How do you add a stdio, HTTP or SSE server?

A stdio server runs as a process on your machine and is the default; an HTTP server runs somewhere else and you pass a URL; SSE is the older remote transport that the docs now mark as deprecated. Pick by where the server lives, not by preference.

stdio. The first two adds, both of which connected:

claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem /tmp
Added stdio MCP server fs with command: npx -y @modelcontextprotocol/server-filesystem /tmp to local config
claude mcp add --env MEMORY_FILE_PATH=/tmp/mem.json --transport stdio memory -- npx -y @modelcontextprotocol/server-memory
Added stdio MCP server memory with command: npx -y @modelcontextprotocol/server-memory to local config

Both are reference servers from the official MCP servers repository, which describes them as educational examples, not production-ready solutions. They suit testing for that reason, and we would not give the filesystem server a wider path than one folder.

HTTP. The add itself worked:

claude mcp add --transport http --scope user claude-code-docs https://code.claude.com/docs/mcp
Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to user config

Headers go in with --header, for example an API key. For servers that sign in with OAuth, claude mcp add accepts --client-id, --client-secret and --callback-port, and you finish the sign-in with /mcp inside a session. On a headless machine, where no browser opens, MCP OAuth Remote Gateway is listed as handling manual OAuth for remote servers. If you are putting your own backend behind an HTTP server, our API and backend skills are where we would start.

SSE. claude mcp add --transport sse legacy-sse https://example.com/sse was accepted. The Claude Code docs call SSE deprecated, and the MCP transport specification (version 2025-06-18) says Streamable HTTP replaces the HTTP+SSE transport from protocol version 2024-11-05. Our advice: use SSE only when the vendor offers nothing else.

The two server types people ask about most work the same way. Design teams connecting Figma can lean on Figma MCP Setup, which by its listing connects Figma servers with the right scoping and authentication, and browse the UX and UI design skills. Teams adding a browser for tests can look at playwright e2e mcp, listed as running, diagnosing and fixing Playwright end-to-end tests. Which servers are worth adding at all is a separate question, answered in our roundup of the best MCP servers for Claude Code.

Can you add a server to Claude Desktop instead?

Yes, but Claude Desktop is a different app with its own config, and claude mcp add does not write to it. What exists is the reverse route: claude mcp add-from-claude-desktop copies servers you already set up in Claude Desktop into Claude Code. On the Linux test machine it stopped immediately:

claude mcp add-from-claude-desktop
Unsupported platform - Claude Desktop integration only works on macOS and WSL.

That matches the docs, which limit the import to macOS and Windows Subsystem for Linux and say it opens an interactive list to pick servers from. We have not run the import on macOS, so we cannot show the selection screen. Our verdict: if you work in both apps, set servers up in Claude Code with claude mcp add and treat the Desktop import as a one-time migration, not as a sync. Nothing we read says the two stay in step after the import.

How do you check that a server is connected?

Run claude mcp list. It starts every configured server, checks its health and prints one line per server. With six servers the check took 7.9 seconds of wall-clock time, measured once:

claude-code-docs: https://code.claude.com/docs/mcp (HTTP) - × Failed to connect
everything: npx -y @modelcontextprotocol/server-everything - ⏸ Pending approval (run `claude` to approve)
fs: npx -y @modelcontextprotocol/server-filesystem /tmp - √ Connected
memory: npx -y @modelcontextprotocol/server-memory - √ Connected
legacy-sse: https://example.com/sse (SSE) - × Failed to connect
weather: https://api.weather.example/mcp (HTTP) - × Failed to connect

Two connected, one waited for project approval and three remote servers failed. The three failures came with the message (shortened in the block above) Proxy refused to open a tunnel: 403 Forbidden, which is our sandbox network refusing the connection. On a normal network you would expect a different result for the real server and a DNS failure for the made-up weather URL; we have not run that.

For the detail on one server, use claude mcp get <name>:

memory:
  Scope: Local config (private to you in this project)
  Status: √ Connected
  Type: stdio
  Command: npx
  Args: -y @modelcontextprotocol/server-memory
  Environment:
    MEMORY_FILE_PATH=/tmp/mem.json

Notice that get prints environment values in plain text. That is fine for a file path and a problem for a token on a shared screen. Inside a session, /mcp shows the same status and is where you sign in to OAuth servers. If you want a second pair of eyes on what you just connected, mcp security audit is listed as auditing MCP configs and tools for credentials, hidden Unicode and tool poisoning, and our security skills collect more of that kind.

How do you remove an MCP server?

Run claude mcp remove <name>, and add --scope when the name exists in more than one place. The first remove was clean:

claude mcp remove legacy-sse
Removed MCP server "legacy-sse" from local config

A typo gives you the list of names that do exist, which is useful:

claude mcp remove nothere
No MCP server named "nothere". Configured servers: claude-code-docs, everything, fs, memory, weather

And a name that lives in two scopes is refused until you pick one (file paths removed):

MCP server "claude-code-docs" exists in multiple scopes:
  - Project config (shared via .mcp.json)
  - User config (available in all your projects)
To remove from a specific scope, use:
  claude mcp remove claude-code-docs -s project
  claude mcp remove claude-code-docs -s user

The docs add that removing a remote server also deletes its stored OAuth tokens, so you sign in again if you add it back.

What do the common errors mean?

Five of the twelve adds failed, and each error points at one fix. In the order we would check them:

MCP server fs already exists in local config. You added the same name twice in the same scope. Remove it first or pick another name. It sits first because it is the most common error in team repos, where someone re-runs a setup script.

Invalid environment variable format: badorder, environment variables should be added as: -e KEY1=value1 -e KEY2=value2. We got this from claude mcp add --env A=1 badorder -- ... and from the short -e form. --env accepts several pairs, so it read the server name as another pair. Put another flag such as --transport stdio between --env and the name, as in our memory example. It ranks second because the message does not tell you the real cause.

Invalid scope: global. Only local, user and project are scopes you type for a normal add. The error also listed internal scopes such as managed and enterprise, which you do not set by hand.

Unsupported platform. The Desktop import outside macOS and WSL, covered above.

Failed to connect. The add worked, the server did not start or answer. Run the server command on its own, outside Claude Code, and read its output. For slow starts the docs describe MCP_TIMEOUT (for example MCP_TIMEOUT=10000 claude for 10 seconds) and the quickstart names a default startup timeout of 30 seconds; we did not test either.

For config files that break in ways the CLI does not explain, MCP Config Doctor is listed as finding JSON errors, broken command and args, relative paths and which definition wins, and mcp server doctor as diagnosing broken connections and transport errors. Neither was run by us. For a lower-level look at what a server returns, our MCP Inspector guide shows how to talk to a server without Claude in between, and the testing and debugging skills cover the wider fault-finding work.

Should you use an MCP server or a skill for this job?

Use an MCP server when Claude needs to reach something outside the repo, such as an API, a database or a design file, and a skill when Claude needs to know how your team does a task. A server gives Claude new tools; a skill gives it instructions and scripts that load only when the task matches. Many jobs need both: a Figma server to read the file and a skill that says how your components are named.

There is a cost argument too. Every connected server adds its tool definitions to the context of each session, whether you use them or not. Our habit is to keep only the servers a project uses in that project's scope and to move user-scope servers you rarely touch back to local. MCP Token Diet is listed as auditing every connected server and measuring the overhead it removes; its listing claims an 80% cut in tool definitions, a vendor figure we have not checked.

If you are still choosing between the two approaches for a recurring task, our comparison of agent skills and MCP goes through the trade-offs, and the workflow automation skills show what the skill side looks like for repeat jobs.

Your next step

Add one stdio server at local scope, run claude mcp list, and only move it to project scope once it connects and holds no secrets. That order caught every mistake in the test session before it could reach a teammate. Commands and flags change between Claude Code versions, so check claude mcp add --help on your version against what you see here.

Written by Samuel Rose, Founder of Agensi. Next scheduled review: 11-12-2026.