Claude MCP Add Command: Scopes, User vs Project and HTTP Servers

You paste a server URL into claude mcp add, press Enter, and the server shows up in one project but vanishes in the next. Or it lands in a teammate's checkout and asks for an approval nobody expected. Almost every confusing result from this command traces back to two decisions: which scope you picked and which transport you used. This article walks through the command flag by flag, shows where each scope stores its data, explains how user and project scopes interact, and gives working examples for HTTP and stdio servers, including the Windows quirk that trips up a lot of people.

What the Add Command Does

claude mcp add registers a Model Context Protocol server with Claude Code so the assistant can call its tools, read its resources and run its prompts. The command installs nothing by itself. It writes a small configuration entry, and Claude Code reads that entry the next time a session starts or when you reconnect from the /mcp menu.

Three decisions shape every call:

• Transport: how Claude Code talks to the server (http, sse or stdio).
• Scope: where the entry is stored and who can see it (local, project or user).
• Name: the label you will type later in claude mcp get, claude mcp remove and the /mcp menu.

The Basic Syntax

Two shapes handle nearly everything you will ever run:

# Remote server reached over a URL
claude mcp add [options] <name> <url>

# Local process started by Claude Code
claude mcp add [options] <name> -- <command> [args...]

Copy Prompt

Put --transport, --scope and --env before the server name. For local processes, the double dash tells the parser that everything after it belongs to the server and not to Claude Code.

💡 Tip: Pass --transport every time, even when a default would work. An explicit flag makes the command read the same in shell history, README files and team chat, whatever version each person runs.

The Three Scopes at a Glance

Claude Code stores each server in one of three places, and the --scope flag (short form -s) picks the place. Leave the flag off and you get local.

The word local confuses people because it sounds like "on my machine," and user scope is on your machine too. The difference is reach. Local is private and limited to one project, while user is private and follows you into every repository.

Local Scope: The Default

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Copy Prompt

Use local scope for experiments, for servers tied to one repository, and for anything carrying a personal credential. Nothing is written into the repository, so there is no risk of committing a token by accident. It is also the scope you land in when you forget the flag, which is why a server added in a hurry seems to disappear when you open a different folder.

Project Scope: Shared in Git

claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp

Copy Prompt

This creates or updates .mcp.json at the project root. Commit it and every teammate gets the same server list after pulling. Because a file in a repository can start processes on your machine, Claude Code asks each person to approve project servers the first time they appear. If someone declined by mistake, claude mcp reset-project-choices clears the earlier answers so the prompt returns.

User Scope: Everywhere You Work

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

Copy Prompt

User scope suits personal tools you want in every repository: a notes app, a documentation search server, a browser helper. The entry lives in ~/.claude.json, travels with your account on that machine, and never touches a repository.

User vs Project: Which Wins?

The choice between user and project scope comes down to one question: who else needs this server? If the answer is "everyone who clones this repo," use project. If the answer is "only me, but in every repo," use user. If the answer is "only me, only here," stay with local.

Which Scope Takes Priority

When the same server name exists in more than one scope, Claude Code uses the most specific definition: local beats project, and project beats user. That order lets you override a shared entry on your own machine without editing a file everyone else uses.

Say the team's .mcp.json defines a server called docs that points at production. You can run this in your own checkout:

claude mcp add --transport http docs https://staging.example.com/mcp

Copy Prompt

The local entry wins, so your session talks to staging while your teammates keep talking to production. Delete the local entry and you fall back to the shared one.

Sharing Through .mcp.json

A project-scope entry is plain JSON, which means you can also write it by hand:

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${DOCS_TOKEN}"
      }
    }
  }
}

Copy Prompt

Claude Code expands ${VAR} and ${VAR:-default} inside command, args, url, headers and env. That is the safe pattern for shared files: commit the structure, and let every person supply their own secret through an environment variable. A real token pasted into .mcp.json ends up in git history, and rotating it is the only reliable fix.

Adding HTTP Servers

HTTP is the recommended transport for remote servers: no local process, no runtime to install, and the vendor handles updates. Most hosted MCP servers publish a URL ending in /mcp, and that is the address you hand to the command.

The Transport Flag

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Copy Prompt

If a vendor's documentation still shows a /sse address, check whether the same service offers an /mcp endpoint before you register the old one. Servers on the deprecated transport keep working for now, but new setups should not start there.

Headers and Bearer Tokens

Servers that accept a static credential read it from a request header. Pass it with --header (short form -H), and repeat the flag when you need more than one:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_TOKEN"

claude mcp add --transport http api https://example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "X-Team: platform"

Copy Prompt

💡 Watch the shell: if you type $GITHUB_TOKEN inside double quotes, your shell expands it before Claude Code ever sees the command, so the stored entry holds the real token. For anything shared, write the ${VAR} form into .mcp.json instead.

Authenticating With OAuth

Many hosted servers skip static tokens and use OAuth. Add the server with no headers, start Claude Code, and run /mcp. Pick the server from the list and follow the browser sign-in. Claude Code stores the resulting credentials and refreshes them for you, so there is nothing to paste into a config file and nothing to commit by mistake.

Stdio Servers and Environment Variables

With stdio, Claude Code starts the server as a child process and talks to it through standard input and output. Choose it for tools that must run on your machine: a local database helper, a filesystem tool, or a script you wrote yourself. Environment variables travel with the --env flag (short form -e).

The Double Dash Separator

claude mcp add --transport stdio --env API_TOKEN=YOUR_TOKEN myserver \
  -- npx -y my-mcp-server

Copy Prompt

Everything before the -- is for Claude Code. Everything after it is the exact command that starts your server, arguments included. Skipping the separator is the most common stdio mistake:

# Wrong: --port is parsed as a Claude Code option
claude mcp add --transport stdio myserver npx server --port 8080

# Right: the server command sits after the double dash
claude mcp add --transport stdio myserver -- npx server --port 8080

Copy Prompt

Windows Needs cmd /c

On native Windows (not WSL), npx is a batch wrapper rather than a real executable, so Claude Code cannot launch it directly. Wrap the command in cmd /c:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Copy Prompt

Without the wrapper you typically see a "Connection closed" error in /mcp, which looks like a server bug but is only a launch failure. The same fix applies when you write the entry by hand: set "command": "cmd" and begin args with "/c", then "npx".

Managing Servers After Adding

Registering a server is half the job. Three commands handle the rest of its life:

claude mcp list            # every server and its connection status
claude mcp get docs        # details for one server
claude mcp remove docs     # delete it

Copy Prompt

Inside a session, /mcp shows the same status live and is also where you sign in to OAuth servers or reconnect one that dropped.

List, Get and Remove

Run claude mcp list first whenever something feels off. It shows what Claude Code actually knows about, from every scope, so you can tell at once whether the server is missing or merely failing. Use claude mcp get <name> to see where an entry came from. If the same name exists in more than one scope, pass --scope to claude mcp remove so you delete the right copy.

The add-json Shortcut

When a vendor hands you a JSON snippet, skip the flags and give it straight to the command:

claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

Copy Prompt

add-json accepts the same --scope flag, so you can drop a snippet into user or project scope in one step. If you already built a set of servers in Claude Desktop, claude mcp add-from-claude-desktop imports them interactively on macOS and WSL.

Fixing Common Failures

Most failures fall into a short list. Match the symptom first, and only then start editing files.

When the table does not settle it, run the same four checks in order:

1. claude mcp list to confirm the server is registered and see its status.
2. claude mcp get <name> to read the exact command or URL Claude Code is using.
3. /mcp inside a session to see the live connection state and reconnect.
4. Paste the stdio command into a plain terminal. If it fails there, the problem is the server, not Claude Code.

When a server will not connect: for a remote server, open the URL in a browser or call it with curl. A 401 or 403 means your header or sign-in is wrong, a 404 usually means the path is wrong (/mcp versus /sse), and a timeout points at the network. For a stdio server, the exact command you registered must run on its own with the same environment variables set.

Put Claude and PicassoIA to Work

Once the scopes are sorted, MCP becomes a way to hand Claude real capabilities, and images are a good one. PicassoIA exposes its generation models through a developer API at https://api.picassoia.com/v1 and through MCP connections. The four models on that surface are PicassoIA Image, PicassoIA Image Editor Pro and two video models. Jobs run asynchronously: Claude submits a prediction, polls it, then reads the finished result. The platform allows 5 concurrent predictions per account, shared across every connection you have open, so a batch of requests from one session will queue instead of running all at once.

💡 Scope tip: the pricing page lists MCP connections on the Pro+, Elite and Infinite plans, so confirm your plan before wiring it up. Register the connection at user scope if you want image generation in every repository, or at local scope if only one project needs it. Copy the connection URL from your PicassoIA account rather than guessing an address.

How to Debug With Claude on PicassoIA

You do not need a terminal to get help with a failing claude mcp add command. Claude Sonnet 5 runs on PicassoIA, and it handles this kind of debugging well:

1. Open the model page from the link above.
2. Paste the exact command you ran, plus the error text from /mcp or the terminal.
3. Say which operating system you use, and whether the server is HTTP or stdio.
4. Ask for the corrected command and a one-line explanation of what was wrong.
5. Run the fix, then confirm it with claude mcp list.

For heavier reasoning about a large .mcp.json, Claude Opus 4.7 is available on the same platform, and Claude 4.5 Haiku answers quick syntax questions at speed.

Make Your Own Images

Reading about scopes is useful, but the real payoff comes from having Claude work with visuals while you code. Open Picasso IA, pick a model such as PicassoIA Image, and generate a few images from your own prompts. Try a header graphic for your next README, a product mockup, or a photo-style scene for a blog post. Once you like the results, connect the same capability to Claude Code through MCP and let the assistant produce images inside your workflow. Experiment freely, compare models side by side, and keep the prompts that work.