How to Add MCP Servers to Claude Code: claude mcp add, Scopes and .mcp.json

MCP servers give Claude Code new tools, like reading your Notion pages, checking Sentry errors or driving a browser. You add them with one command: claude mcp add.

This guide covers every transport, all three scopes, the .mcp.json file, OAuth sign-in and the fixes for the errors people hit most. It is up to date with Claude Code 2.1.319 from November 2026.

What MCP does in Claude Code

MCP stands for Model Context Protocol. It is an open standard that lets an AI app talk to outside tools and data through a common interface.

Each MCP server exposes tools. Once you add a server, Claude Code can call those tools during a task, just like its built-in Read or Bash tools.

• Remote servers: hosted services such as Notion, Sentry or Asana, reached over HTTP.
• Local servers: programs on your machine, started with a command like npx, that talk over stdio.
• claude.ai connectors: servers you added on claude.ai show up in Claude Code too when you log in with a claude.ai account.

Tip: Not sure which servers to try? My list of the best MCP servers is a good starting point. To build your own, see how to build an MCP server in Python.

How to add your first MCP server

Here is the full flow for a remote HTTP server. Notion is used as the example, but the steps are the same for any hosted server.

1. Install Claude Code. If you do not have it yet, follow my Claude Code install guide.
2. Open your project folder. cd into the repo where you want the server. The default scope is tied to this folder.
3. Add the server. Run claude mcp add --transport http notion https://mcp.notion.com/mcp.
4. Check it saved. Run claude mcp list. You should see notion with its status.
5. Start Claude Code. Run claude, then type /mcp.
6. Sign in. If the status reads “Needs authentication”, pick the server in /mcp and finish the browser login.
7. Use it. Ask something like “Find my Notion page about the Q4 roadmap and summarise it.”

Note: Server names added with claude mcp can only contain letters, numbers, hyphens and underscores.

HTTP, stdio, SSE and WebSocket servers

The transport is how Claude Code talks to the server. Pick it with --transport (or -t).

Stdio servers and the double dash

For a local server, the -- separator is important. Everything before it is for Claude Code. Everything after it is the command that starts the server.

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• Why it matters: without --, a server flag such as --port is read as a Claude Code option.
• Env vars: --env takes several KEY=value pairs. Put another option between --env and the server name, or the name is read as a pair.

HTTP falls back to SSE

On Claude Code v2.1.265 or later, an HTTP add tries HTTP first. If the server does not accept it, Claude Code switches to SSE for you.

Adding from JSON or Claude Desktop

If a server’s docs give you a JSON block, use add-json.

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

Already set up servers in Claude Desktop? Run claude mcp add-from-claude-desktop and pick which ones to import. This works on macOS and WSL only.

Local, project and user scopes

The scope decides where a server is saved and who gets it. Set it with --scope (or -s).

When two scopes define the same server, the order is local, then project, then user, then plugin, then claude.ai connectors. Definitions are not merged field by field. The higher one wins outright.

• Personal API keys: use local or user scope, so the key never lands in git.
• Team tools: use project scope and commit .mcp.json.
• Everyday helpers: use user scope for servers you want in every repo.

The .mcp.json file and environment variables

A project-scoped server lives in .mcp.json at the root of your repo. Here is a full example with variable expansion.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

• Syntax: ${VAR} and ${VAR:-default} work in command, args, env, url and headers.
• Unset vars: a variable with no value and no default gives a warning and stays as literal text.
• Always set type: an entry with a url but no type is an error, because it is read as stdio.
• Project path: stdio servers get CLAUDE_PROJECT_DIR. In project entries, write ${CLAUDE_PROJECT_DIR:-.}.

Warning: For remote url and headers, sensitive variables such as ANTHROPIC_API_KEY, NPM_TOKEN and HTTPS_PROXY read as empty. This stops a cloned repo from sending your secrets away. Copy the value into a variable with your own name if a server really needs it.

Project approval

Interactive sessions ask before using servers from a project’s .mcp.json. claude -p and Agent SDK runs load them without asking. To reset your answers, run claude mcp reset-project-choices.

OAuth and API key authentication

OAuth sign-in

Most hosted servers use OAuth. Add the server, then sign in from /mcp or the shell.

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

Use --no-browser to print the login URL instead of opening it, which helps over SSH. Run claude mcp logout sentry to sign out.

Servers that need a client ID

Some servers do not support dynamic client registration. Pass your own credentials when you add them.

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

• Secret input: --client-secret asks for the secret with masked input. In CI, set MCP_CLIENT_SECRET instead.
• Redirect URI: register http://localhost:PORT/callback with the provider.
• Scopes: limit OAuth scopes with oauth.scopes in the server’s JSON entry.

API keys and custom headers

For a simple token, add a header with --header (or -H). For tokens that change, a headersHelper command can print a JSON object of headers. It has a 10-second limit and only runs after you trust the project folder.

Managing servers: list, get, remove and /mcp

Status icons in /mcp tell you what is wrong at a glance: Connected, Needs authentication, Failed to connect or Pending approval. For more slash commands, see my Claude Code commands cheat sheet.

Timeouts, output limits and MCP tasks

• Startup timeout: MCP_TIMEOUT=10000 claude gives servers 10 seconds to start.
• Output cap: MAX_MCP_OUTPUT_TOKENS defaults to 25,000 tokens, with a warning above 10,000.
• Big text results: results over 50,000 characters are saved to a file unless the server raises the limit.
• Per-server timeout: add "timeout": 600000 (milliseconds) to a server entry.
• Idle timeout: 5 minutes for remote servers and 30 minutes for stdio by default.
• Auto background: calls still running after 2 minutes move to /tasks.

MCP tasks in 2.1.319

Some servers can run a long call as a task. In version 2.1.319, Claude Code moves such tasks to the background right away and tells Claude the result when done. They now work without feature flags, including on Bedrock, Vertex, Foundry and LLM gateways.

• Track: watch tasks in /tasks and stop one with x.
• Wait instead: set CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND to 1.
• Turn off: set CLAUDE_CODE_DISABLE_MCP_TASKS=1.

Writing .mcp.json is a protected action in auto mode, so the classifier reviews it. See my auto mode guide for details.

Troubleshooting MCP in Claude Code

Error: has a “url” but no “type”

Add "type": "http", "sse" or "ws" to that entry in .mcp.json. Without a type, Claude Code treats it as a stdio server.

Server shows Failed to connect

Open /mcp and read the Issue line, which includes the HTTP status. A 401 means bad or missing credentials, so sign in again or fix the header.

Local server ignores its flags

You probably left out the -- separator. Re-add the server with the server command after --.

Project server shows Pending approval

Start claude in that folder and approve it. If you said no by mistake, run claude mcp reset-project-choices.

Server is slow to start

Raise the startup timeout with MCP_TIMEOUT, for example 10000 for 10 seconds.

A claude.ai connector is missing

Connectors only load with a claude.ai login. If ANTHROPIC_API_KEY or a third-party provider is active, run /status, remove it, then /login again.

Tool output gets cut off

Raise MAX_MCP_OUTPUT_TOKENS, for example to 50000. Bigger outputs also use more of your context, so check my Claude API pricing guide if you pay per token.

Frequently Asked Questions

What is the default MCP scope in Claude Code?

Local. The server is saved in ~/.claude.json and only loads in the current project, for you alone.

Where is .mcp.json stored?

In the root of your project. It holds project-scoped servers and is meant to be committed to git.

Should I use HTTP or SSE?

Use HTTP. SSE is deprecated, and since v2.1.265 an HTTP add falls back to SSE automatically if needed.

How do I log in to an MCP server?

Run /mcp inside Claude Code and pick the server, or run claude mcp login <name> in your shell.

Can I share MCP servers with my team?

Yes. Add them with --scope project so they go into .mcp.json, then commit the file. Keep secrets in environment variables, not in the file.

Can a subagent have its own MCP server?

Yes. List it in the subagent’s mcpServers frontmatter field. My subagents guide has an example.

How much MCP output can Claude Code read?

25,000 tokens per tool result by default. Change it with MAX_MCP_OUTPUT_TOKENS.

Sources

• Claude Code docs: Connect Claude Code to tools via MCP
• Claude Code changelog on GitHub (2.1.319)
• Model Context Protocol official site
• Claude Code docs: Permission modes