# Claude Code MCP setup: add, scope and manage servers

URL: https://agentvera.dev/en/blog/claude-code-mcp-setup/ · Published: 2026-10-28

How to add MCP servers to Claude Code: claude mcp add for stdio and HTTP, scopes, .mcp.json, /mcp and OAuth, Claude Desktop import, timeouts and output limits.

**In short:**

- Add a server with claude mcp add: options go before the name, and a local stdio server’s command goes after --. Remote servers use --transport http with a URL.
- The scope decides where it is stored: local (default) and user in ~/.claude.json, project in a .mcp.json at the repo root that you can commit.
- Run /mcp in a session to check status, sign in to OAuth servers and turn servers off. MCP_TIMEOUT and MAX_MCP_OUTPUT_TOKENS fix most startup and output problems.
- Claude Code asks before it uses a project’s .mcp.json servers. Review them like any code from the repo, and keep tokens in ${VAR} references, not in the file.

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](https://code.claude.com/docs/en/mcp "Connect Claude Code to tools via MCP") as of October 2026. If MCP itself is new to you, start with [what an MCP server is](/en/blog/what-is-mcp-server/ "What is an MCP server"); if you want to know which servers to add, see [the best MCP servers for coding](/en/blog/best-mcp-servers-for-coding/ "Best MCP servers for coding").

## Quick reference

| Task | Command |
| --- | --- |
| Add a local (stdio) server | `claude mcp add <name> -- <command> [args...]` |
| Add a remote (HTTP) server | `claude mcp add --transport http <name> <url>` |
| Add from a JSON snippet | `claude mcp add-json <name> '<json>'` |
| Share with the team | add `--scope project` (writes `.mcp.json`) |
| Use in all your projects | add `--scope user` |
| List servers and their health | `claude mcp list` |
| Show one server’s details | `claude mcp get <name>` |
| Remove a server | `claude mcp remove <name>` |
| Sign in to an OAuth server | `/mcp` in a session, or `claude mcp login <name>` |
| Import from Claude Desktop | `claude mcp add-from-claude-desktop` |
| Status, sign-in, disable, reconnect | `/mcp` inside Claude Code |

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](/en/glossary/mcp/ "MCP") server reaches Claude Code in one of three ways:

| Transport | What it is | When to use it |
| --- | --- | --- |
| `stdio` | A local process Claude Code starts and talks to over stdin and stdout | Servers you run with `npx`, `uvx`, Docker or your own script |
| `http` | A remote server over streamable HTTP | Hosted services: Notion, Sentry, GitHub, Stripe and others. Anthropic recommends it for remote servers |
| `sse` | Server-Sent Events | Older remote servers only. The docs mark SSE as deprecated |

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.

```bash
# 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:

```bash
# 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:

```bash
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:

| Scope | Flag | Stored in | Who gets it |
| --- | --- | --- | --- |
| Local (default) | `--scope local` | `~/.claude.json`, under this project’s path | Only you, only in this project |
| Project | `--scope project` | `.mcp.json` at the project root | Everyone who clones the repo |
| User | `--scope user` | `~/.claude.json` | Only you, in every project |

```bash
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:

```json
{
  "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:

```bash
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](/en/blog/claude-code-hooks-guide/ "Claude Code hooks guide").

## 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:

```bash
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:

```bash
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:

```bash
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

| Symptom | What to try |
| --- | --- |
| Server fails to connect | `claude mcp get <name>` for the error, then **Reconnect** in `/mcp` |
| Slow server times out at startup | Start with `MCP_TIMEOUT=10000 claude` (ten seconds) |
| Long tool calls get cut off | `MCP_TOOL_TIMEOUT` for all servers, or `"timeout"` per server in `.mcp.json` |
| “Output exceeds” warning or truncated results | Claude Code warns above 10,000 tokens and caps output at 25,000 by default. Raise it with `MAX_MCP_OUTPUT_TOKENS=50000` |
| Flags of the server are ignored or rejected | Put Claude Code’s options before the name and the server command after `--` |
| `${VAR}` warning in `/mcp` | Set the variable in the shell you start Claude Code from, or add a `:-default` |
| Server skipped at load | The name is reserved (`workspace`, `claude-in-chrome`, `computer-use` and a few more); rename it |
| Token works in curl but not here | Look for a trailing space or newline in a pasted token; Claude Code warns about hidden whitespace |

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](/en/glossary/prompt-injection/ "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](/en/blog/ai-coding-agent-security/ "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](/en/features/mcp-manager/ "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?](/en/blog/what-is-mcp-server/ "What is an MCP server")
- [Best MCP servers for coding agents](/en/blog/best-mcp-servers-for-coding/ "Best MCP servers for coding")
- [MCP manager](/en/features/mcp-manager/ "MCP manager")
- [Claude Code agent](/en/agents/claude-code/ "Claude Code in AgentVera")

## Frequently asked questions

**How do I add an MCP server to Claude Code?** Run claude mcp add in your terminal. For a local server: claude mcp add <name> -- <command> [args]. For a remote one: claude mcp add --transport http <name> <url>. Then run claude mcp list, or /mcp inside a session, to check that it connects.

**Where does Claude Code store MCP servers?** Local-scoped servers (the default) and user-scoped servers live in ~/.claude.json, the first under the current project’s path. Project-scoped servers live in a .mcp.json file at the project root, which you can commit for your team.

**What is the difference between local, project and user scope?** Local is only you, only this project. Project is everyone who clones the repo, through .mcp.json. User is only you, in every project on your machine. If one name exists in several scopes, local wins over project, and project over user.

**How do I sign in to an MCP server that uses OAuth?** Add it with --transport http, then run /mcp inside Claude Code and pick Authenticate, or run claude mcp login <name> from your shell. The browser login finishes the flow, and Claude Code stores and refreshes the token for you.

**Why does my MCP server time out or cut its output?** Slow servers can need a longer startup timeout: start Claude Code with MCP_TIMEOUT=10000 for ten seconds. Tool output is capped at 25,000 tokens by default, with a warning above 10,000; raise the cap with MAX_MCP_OUTPUT_TOKENS.

**Is it safe to use a .mcp.json from a cloned repo?** Treat it like any code you didn’t write. Claude Code asks for approval before it uses project servers in an interactive session, and a cloned repo can’t approve its own servers. Read each command and URL before you say yes.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/