How to Add an MCP Server to Claude Code: Commands and Scopes

To add an MCP server to Claude Code, you run one command in your terminal and then check it inside a session. Run claude mcp add with --transport http, a name and the URL for a remote server, or with --transport stdio, a name, a -- separator and the start command for a server on your machine. Then type /mcp in Claude Code to confirm it's connected.

claude mcp add --transport http <name> <url>
claude mcp add --transport stdio <name> \
  -- <command> [args...]

This tutorial covers both commands, the three scopes and where each one saves its config, how to share servers with a team through .mcp.json, and the errors people hit most. Every command was checked against the official Claude Code MCP docs on October 30, 2026. If you want ideas for which servers to add, see our list of MCP servers worth setting up for Claude Code.

Pick the transport first

An MCP server reaches Claude Code in one of two main ways, and the command changes with it.

Remote or local?

Remote (HTTP)

The vendor hosts the server

• You add a URL
• Sign-in is often OAuth in the browser
• Examples: Notion, Sentry, Stripe

vs

Local (stdio)

The server runs on your machine

• You add a command, such as npx
• Keys go in with --env
• Examples: database tools, your own server

The docs list SSE as deprecated. From Claude Code v2.1.265, --transport http tries HTTP first and switches to SSE on its own, so you can use the HTTP form for older SSE-only servers too.

Add a remote server

The basic form is the transport, a name you choose, then the URL:

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

If the server takes an API key in a header instead of a browser sign-in, add --header (short form -H):

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Most hosted servers use OAuth. After adding one, start Claude Code, type /mcp and follow the browser login. You can also sign in from your shell with claude mcp login <name>. One catch: a headless claude -p run or an Agent SDK script can't complete the OAuth flow, so sign in once from an interactive session first.

Add a local server

Local servers run as a process that Claude Code starts. Everything after the -- is the command that starts the server, passed through untouched:

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

Two details trip people up:

• The -- separator is required. Claude's own options (--transport, --env, --scope) go before it. The server command and its arguments go after it.
• Put another option between --env and the name. --env accepts several KEY=value pairs, so if the server name comes straight after it, Claude Code reads the name as another pair and rejects it. That's why the example above puts --transport stdio in the middle.

If you're building your own server, how to build an MCP server walks through one in TypeScript and adds it with this same command.

Choose a scope

Every claude mcp add command saves to a scope. Set it with --scope (short form -s):

A rule of thumb for client work: use project for servers everyone on the repo needs (the client's database, their issue tracker), user for your personal tools across every project, and local for experiments or servers that carry your own credentials.

If the same server name exists in more than one place, Claude Code uses the highest one and doesn't merge settings across them. The order is local, then project, then user, then plugin servers, then claude.ai connectors.

Use .mcp.json for a team

A project-scoped server lands in .mcp.json at the root of the repo. You can also write the file by hand:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Keep secrets out of it, because the file usually gets committed. Claude Code expands environment variables in command, args, env, url and headers:

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

${VAR} reads a variable and ${VAR:-default} falls back to the default when it isn't set. For safety, credential variables such as ANTHROPIC_API_KEY read as empty inside a remote server's url and headers, so a repo can't send your keys to a server it names.

When a teammate opens the project, Claude Code asks them to approve the servers in .mcp.json before using them in an interactive session. claude mcp list shows unapproved ones as pending. To clear those approval choices and be asked again, run claude mcp reset-project-choices.

Other ways to add a server

• From a JSON block. If a server's setup instructions give you an mcpServers entry written for another client, pass the inner object to claude mcp add-json, not the wrapper:

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

• From Claude Desktop. claude mcp add-from-claude-desktop opens a picker and imports the servers you choose. The docs say it works on macOS and Windows Subsystem for Linux only.
• From claude.ai. If you log in to Claude Code with a claude.ai account, connectors you added in claude.ai show up in Claude Code automatically.

Manage and remove servers

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

Inside a session, /mcp shows status and handles sign-in. For an OAuth server, run claude mcp logout <name> before remove: removing deletes the stored tokens but doesn't revoke them.

Once connected, a server's resources can be pulled into a prompt with @, in the format @server:protocol://resource/path, for example @github:issue://123.

Fix common problems

• The server times out on startup. Raise the startup timeout with MCP_TIMEOUT, in milliseconds: MCP_TIMEOUT=10000 claude.
• A tool's output gets cut off. The output limit defaults to 25,000 tokens. Raise it with MAX_MCP_OUTPUT_TOKENS=50000.
• A server in .mcp.json never loads. It's probably waiting for approval. Start claude interactively and approve it.
• A hand-written entry with a URL fails. An entry with a url but no type is read as stdio and errors. Add "type": "http".
• A variable shows up literally as ${VAR}. It isn't set in your environment and has no default. claude mcp list warns about it.

Learn to build with Claude Code

The Stride AI Coding course teaches Claude Code and Codex for building tools for clients, including wiring MCP servers into real projects. Bring a stuck setup to the weekly live calls, or start with the free guide library.

FAQ

What is the command to add an MCP server to Claude Code?

claude mcp add. For a remote server use claude mcp add --transport http <name> <url>. For a local one use --transport stdio, the name, a -- separator and the command that starts the server. Add --scope project or --scope user to change where it's saved.

Where is the Claude Code MCP config file?

Local and user scope servers are saved in ~/.claude.json. Project scope servers are saved in .mcp.json in the project root, which you can commit so your team gets the same servers.

How do I check that an MCP server is connected?

Type /mcp inside Claude Code to see each server's status and sign in where needed. From your terminal, claude mcp list shows every configured server, and claude mcp get <name> shows one in detail.

Why doesn't my .mcp.json server show up?

Claude Code asks for approval before using project servers in interactive sessions. Start claude and approve it. Also check that the JSON is valid, that a remote entry has "type": "http", and that any ${VAR} it uses is set.