How to Set Up MCP Servers in Claude Code

Steps

1. 01

   Understand the three scopes: local, user, and project

   Claude Code v2.1.183 supports three scopes via the `-s/--scope` flag on `add`, `add-json`, `add-from-claude-desktop`, and `remove`. The default is `local`. - **local** (default): Stores the server in `~/.claude.json` scoped to the current project directory. Private to you — not shared with teammates, and not available in other directories. This is what plain `claude mcp add <name> ...` writes. - **user**: Also stored in `~/.claude.json` but available in every Claude Code session regardless of directory. Pass `-s user` (or `--scope user`) to register at this scope. - **project**: Stored in a `.mcp.json` file at the repository root. Shared with anyone who clones the repo, but every user must explicitly approve the servers before Claude can call their tools. Practical rule: use `local` (the default) for project-specific servers you are the only developer; use `user` for personal utilities you always want available; use `project` for team-shared servers you want to ship with the repository.

   # Default: local scope (current project, private to you)
   claude mcp add my-server -- my-command --some-flag arg1
   
   # Explicitly user scope (available in all sessions)
   claude mcp add -s user my-server -- my-command --some-flag arg1
   
   # Explicitly project scope (written to .mcp.json, shared with the repo)
   claude mcp add -s project my-server -- my-command --some-flag arg1

2. 02

   Add a stdio server (local process)

   A stdio server is a local command Claude Code launches as a child process and communicates with over stdin/stdout. This is the most common form for open-source MCP packages installed via npm or published as binaries. Pass the command after `--` to avoid flag ambiguity. To inject an API key as an environment variable, use `-e KEY=value` (long form `--env`) before the `--`. The flag accepts multiple values — repeat it once per variable.

   # Basic stdio server (lands in local scope by default)
   claude mcp add my-server -- my-command --some-flag arg1
   
   # stdio server with an environment variable injected
   claude mcp add my-server -e API_KEY=xxx -- npx my-mcp-server
   
   # Multiple env vars
   claude mcp add my-server -e API_KEY=xxx -e REGION=us-east-1 -- npx my-mcp-server

3. 03

   Add a remote HTTP server

   HTTP transport connects to a hosted MCP endpoint over HTTP. Use `--transport http` (or `-t http`) and provide the full URL. Some hosted servers require a bearer token in an Authorization header; pass it with `--header` (short form `-H`). The flag accepts multiple values — repeat it once per header.

   # HTTP server (no auth)
   claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
   
   # HTTP server with a bearer token header
   claude mcp add --transport http corridor https://app.corridor.dev/api/mcp --header "Authorization: Bearer <your-token>"
   
   # Short forms (-t and -H) are equivalent
   claude mcp add -t http corridor https://app.corridor.dev/api/mcp -H "Authorization: Bearer <your-token>"

4. 04

   Add a remote SSE server

   SSE (Server-Sent Events) transport connects to a hosted endpoint that streams events over HTTP. Use `--transport sse` (or `-t sse`) and provide the full SSE endpoint URL. Like HTTP servers, SSE servers may require auth headers passed with `--header` / `-H`.

   # SSE server (no auth)
   claude mcp add --transport sse my-sse-server https://example.com/mcp/sse
   
   # SSE server with a bearer token header
   claude mcp add --transport sse my-sse-server https://example.com/mcp/sse --header "Authorization: Bearer <your-token>"

5. 05

   Add a server from raw JSON (add-json)

   If you already have a server's full MCP JSON descriptor — for example copied from a vendor's docs — you can register it in one shot without constructing individual flags. Pass the server name and the JSON object as the second argument. The `-s/--scope` flag is also available on this subcommand.

   claude mcp add-json <name> '<json-descriptor>'

6. 06

   Import servers from Claude Desktop (Mac and WSL only)

   If you have already configured MCP servers in the Claude Desktop app, you can import all of them into Claude Code in a single command. This reads the Claude Desktop config file and adds each server. By default the servers land in `local` scope (current project, private to you). Pass `-s user` to import them into user scope (available in all sessions) or `-s project` to write them into `.mcp.json`. Only available on macOS and Windows Subsystem for Linux.

   # Import into local scope (default — current project, private)
   claude mcp add-from-claude-desktop
   
   # Import into user scope (available in every session)
   claude mcp add-from-claude-desktop -s user

7. 07

   Use project-scope servers with .mcp.json and the approval flow

   When a `.mcp.json` file exists in your project root, Claude Code reads it at startup and shows any new servers as pending approval. Each developer must explicitly approve them before the tools become available — this prevents a malicious repo from silently running arbitrary code on a clone. You can create `.mcp.json` by running `claude mcp add -s project ...`, or by committing the file directly. To reset which servers you have approved or rejected for the current project (so Claude will ask again), run the reset command.

   # .mcp.json lives at the repository root alongside your .git folder
   # Structure (confirm exact schema on Anthropic docs):
   {
     "mcpServers": {
       "my-server": {
         "command": "npx",
         "args": ["my-mcp-server"]
       }
     }
   }
   
   # Reset approval choices so Claude asks again on next startup
   claude mcp reset-project-choices

8. 08

   List, inspect, and remove servers

   Three subcommands cover day-to-day management. `list` shows every registered server and its transport type. `get` shows the full config for one server by name — useful to verify a token or URL without re-reading the config file. `remove` deletes the registration by name. The `-s/--scope` flag is available on `remove` to target a specific scope.

   # Show all registered servers
   claude mcp list
   
   # Show full config for one server
   claude mcp get <name>
   
   # Remove a server
   claude mcp remove <name>

9. 09

   Run Claude Code itself as an MCP server

   `claude mcp serve` starts Claude Code in server mode: it exposes its own capabilities (code editing, bash, file read/write) as MCP tools that another agent or orchestrator can call. This is useful when you want a parent agent to delegate coding sub-tasks to Claude Code programmatically, or when building multi-agent pipelines where Claude Code is one node.

   claude mcp serve

10. 10

    Point Claude Code at a custom MCP config file

    By default Claude Code reads `~/.claude.json` for local- and user-scoped servers and `.mcp.json` in the project root for project-scoped servers. If you need to load a different config file — for example a shared team config checked in at a non-standard path — use the `--mcp-config` flag when starting Claude Code.

    claude --mcp-config /path/to/my-mcp.json

Troubleshooting

claude mcp add reports 'command not found' for the server command

The command must be on the PATH that Claude Code sees at startup, which may differ from your interactive shell. For npm global packages, run 'npm list -g <package>' to confirm it is installed globally, or use 'npx <package>' instead of a bare binary name so npm resolves it at runtime. On some systems npm global bin is not in the PATH available to non-interactive processes — add it explicitly to your shell profile and restart Claude Code.

Tools from a project .mcp.json server never appear — Claude says it has no tools from that server

New servers added via .mcp.json start as pending-approval. Claude Code will show an approval prompt on startup; if you missed it, run 'claude mcp list' to see the server's status. Run 'claude mcp reset-project-choices' to force Claude to ask again on next startup, then approve the server when prompted.

HTTP or SSE server returns 401 or tools fail after adding with --transport http or --transport sse

Verify the bearer token with 'claude mcp get <name>' and check it matches what the server expects. Some servers require the header key to be exactly 'Authorization' with the value 'Bearer <token>' — confirm the exact format in the server's own documentation. Token expiry is also a common cause; regenerate and re-run 'claude mcp add' with the fresh token.

Performance degrades after connecting several MCP servers — Claude misuses or ignores tools

Connecting more than 5-7 servers causes 'tool bloat': the combined tool list overflows the context Claude can reason about effectively, leading to wrong tool selection or tools being ignored. Disconnect servers you are not actively using with 'claude mcp remove <name>'. Keep the active list to 2-3 servers for best results.

'claude mcp add-from-claude-desktop' fails or finds no servers

This command only works on macOS and Windows Subsystem for Linux — it is not available on native Linux. On macOS, confirm that the Claude Desktop app has been installed and launched at least once (so its config file exists). If the import succeeds but a server still does not appear, check that the command path in the Claude Desktop config is accessible from your current user environment.

A server added without -s user is not available in a different project directory

Plain 'claude mcp add' writes to local scope, which is scoped to the current project. The server will not appear when you run Claude Code in a different directory. Re-add it with '-s user' to make it available everywhere, or add it inside each project where you need it.