Claude Code MCP setup: add, scope and manage servers

To set up MCP in Claude Code, run claude mcp add in your terminal. A local server is claude mcp add <name> -- <command>, a remote one is claude mcp add --transport http <name> <url>, and --scope decides whether the server is only for you in this project (local, the default), for the whole team through a .mcp.json file (project), or for you in every project (user). Then type /mcp inside a session to check the connection and sign in to servers that use OAuth.

This guide walks through every step: transports, the -- separator, environment variables and headers, scopes, editing .mcp.json by hand, the list, get and remove commands, OAuth, importing from Claude Desktop, timeouts and output limits, and what to check before trusting a project’s servers. The commands come from Anthropic’s Claude Code MCP documentation as of October 2026. If MCP itself is new to you, start with what an MCP server is; if you want to know which servers to add, see the best MCP servers for coding.

Quick reference

Short flags work too: -t for --transport, -s for --scope, -e for --env and -H for --header.

Pick a transport: stdio, HTTP or SSE

An MCP server reaches Claude Code in one of three ways:

You rarely need --transport sse any more. Since Claude Code 2.1.265, claude mcp add --transport http tries HTTP first and switches to SSE on its own when the server doesn’t accept HTTP. On older versions, pass --transport sse explicitly.

Add a local stdio server

The rule that trips most people up: Claude Code’s own options (--transport, --scope, --env) go before the server name, and everything after -- is the server’s command, passed through untouched.

# Basic form
claude mcp add [options] <name> -- <command> [args...]

# Playwright, run with npx
claude mcp add playwright -- npx -y @playwright/mcp@latest

# A server that needs an API key in its environment
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Without --, a server flag such as --port 8080 would be read as a Claude Code option and the command fails. One more catch from the docs: --env accepts several KEY=value pairs, so if the server name comes right after it, the name is read as another pair and rejected. Put another option, such as --transport stdio, between them, as in the example above.

Claude Code sets CLAUDE_PROJECT_DIR in each stdio server’s environment, so a server can find the project root without depending on the working directory.

Add a remote HTTP server

Remote servers take a URL instead of a command. Add headers with --header when the server wants an API key or a bearer token:

# A hosted server that signs in with OAuth
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A server that takes a static token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

A header you type here is stored in plain text in the config file. For anything shared, prefer OAuth or a ${VAR} reference in .mcp.json, covered below.

If you already have a JSON definition from a server’s README, skip the flags and paste it with add-json. It takes the object that would sit inside mcpServers, not the whole file:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Choose a scope

Every claude mcp add writes to one of three scopes:

claude mcp add --transport http stripe https://mcp.stripe.com                      # local
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

A rule of thumb: personal tools and anything with your own credentials go in user or local; servers the whole team needs to work on the repo go in project.

Note that “local” here is not .claude/settings.local.json. Local MCP servers live in ~/.claude.json in your home folder.

When the same name is defined in more than one place, Claude Code takes the highest one and does not merge fields: local first, then project, then user, then plugin servers, then claude.ai connectors. If two scopes point the same name at different endpoints, claude mcp list and /mcp warn you.

Write .mcp.json by hand

A project-scoped server is just a .mcp.json file you can edit and review in pull requests:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${VAR} expands to an environment variable and ${VAR:-default} falls back to a default. Expansion works in command, args, env, url and headers, which is how you commit the file without committing tokens: each developer sets API_KEY in their own shell. If a variable is missing and has no default, claude mcp list and /mcp warn and leave the text unexpanded.

A per-server "timeout" in milliseconds sets a hard limit for that server’s tool calls.

Manage servers: list, get, remove and /mcp

From the shell:

claude mcp list          # every server, with its connection status
claude mcp get notion    # details for one server, including why it failed
claude mcp remove notion # delete it from its scope

list and get show the failure detail with credentials redacted. A project server you haven’t approved yet shows as pending until you run claude interactively and approve it.

Inside a session, /mcp is the control panel. It shows each server’s status and tool count, and from a server’s menu you can authenticate, re-authenticate, clear authentication, reconnect, or toggle the server off without deleting its config. /mcp reconnect all retries every failed server at once (Claude Code 2.1.284 or later).

Connected servers add more than tools. Type @ to reference a server’s resources next to your files, and type / to see its prompts, listed as /servername:promptname (MCP). Tools themselves are named mcp__<server>__<tool>, which is the name you use in permission rules and in hook matchers.

Sign in to OAuth servers

Many hosted servers, such as Sentry, Notion or Linear, use OAuth instead of a static token. Add the server with --transport http and no header, then sign in:

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

Inside Claude Code, run /mcp, pick the server and choose Authenticate. Your browser opens, you log in, and Claude Code stores the token and refreshes it. You can also do it from the shell without opening a session:

claude mcp login sentry               # opens the browser
claude mcp login sentry --no-browser  # prints the URL, for SSH sessions
claude mcp logout sentry              # forget the stored credentials

Headless runs (claude -p) can’t show a sign-in, so sign in once interactively first. Some servers need a fixed callback port or a pre-registered OAuth app; for those, pass --callback-port, --client-id and --client-secret when you add the server. The secret is asked for with masked input, or read from MCP_CLIENT_SECRET in CI.

Import servers from Claude Desktop

If you already set up servers in the Claude Desktop app, you don’t need to retype them:

claude mcp add-from-claude-desktop

A dialog lets you pick which servers to import. As of October 2026 this works on macOS and in WSL only. Add --scope user to import into your user config. Server names may only contain letters, digits, hyphens and underscores, so a Desktop server named with a space is skipped and reported, and a name that already exists gets a suffix such as server_1.

Troubleshooting

Long text results have a second limit: a result over 50,000 characters is saved to a file instead of going straight into the context.

Remote servers that drop mid-session are retried up to five times with backoff, but stdio servers are not retried automatically, so a crashed local server needs a reconnect from /mcp.

Context is the other cost to watch. Claude Code uses tool search by default on current models: only tool names and server instructions load at the start, and full tool definitions load when Claude needs them. That keeps a long server list cheap, but each server is still one more thing that can fail or be misused, so keep the list short. For scripts, --mcp-config <file> loads extra servers for one run, and --strict-mcp-config makes Claude Code use only those.

Security: project servers are code from the repo

A .mcp.json in a repo can start any local command or point at any URL. That is what makes it useful for teams, and it is also why Claude Code treats it carefully:

• Approval first. In an interactive session, Claude Code asks before it uses project-scoped servers. claude mcp reset-project-choices clears your past answers.
• A repo can’t approve itself. Settings like enableAllProjectMcpServers committed to the project’s .claude/settings.json are ignored until you trust the folder, and the server stays pending. Approvals from your own user settings still count.
• Headless runs don’t ask. In claude -p and Agent SDK runs there is no prompt, so project servers load without one. To block a server in every mode, list it in disabledMcpjsonServers.
• Credentials stay home. In a remote server’s url and headers, sensitive variables such as ANTHROPIC_API_KEY expand to empty, even if they are set, so a project can’t quietly send your Anthropic key to its server.
• Trust what the server returns as little as what it runs. Anthropic’s docs warn that servers fetching outside content can expose you to prompt injection. Prefer read-only modes and narrow tokens.

Before you approve, read the command, args and url of each server the same way you’d read a postinstall script. More on the wider picture in AI coding agent security.

When you run more than Claude Code

Everything above is per CLI. Codex keeps its servers in ~/.codex/config.toml, Gemini CLI in its own settings.json, and each tool has its own commands. If Claude Code is the only agent you use, claude mcp add and a committed .mcp.json are all you need, and nothing here requires another tool.

If you run several coding CLIs, the lists drift apart. That is the problem the MCP manager in AgentVera, the desktop app that publishes this blog, is built for:

• Added once, connected at launch. You register stdio, HTTP and SSE servers in AgentVera, and they connect when agents start: to all agents, the ones you choose, a group’s agents or a team role. Claude Code, Codex and the other CLI agents that take MCP get them.
• In step with Claude Code’s own config. Servers from Claude Code’s and Codex’s settings are listed with their health; you can import them into AgentVera or remove them from the CLI, and AgentVera’s servers can be written to the CLI settings too.
• One sign-in, no tokens in files. Remote servers go through AgentVera’s gateway, you sign in to an OAuth server once in the app, and the agent’s CLI holds no header or token. Secret environment variables and headers are kept in your OS keychain.
• Costs you can see. A connection test lists a server’s tools, prompts and resources with an approximate token cost per tool.

Wrapping up

Start with one server you actually need, added with claude mcp add in the narrowest scope that works. Check it with claude mcp list or /mcp, sign in with /mcp or claude mcp login, and move it to a committed .mcp.json only when the whole team needs it, with tokens in ${VAR} references. When something breaks, claude mcp get, MCP_TIMEOUT and MAX_MCP_OUTPUT_TOKENS solve most of it.

Read more:

• What is an MCP server?
• Best MCP servers for coding agents
• MCP manager
• Claude Code agent