How to add an MCP server to Claude Code

Short answer: For a remote server, run claude mcp add --transport http <name> <url>, for example claude mcp add --transport http notion https://mcp.notion.com/mcp. For a server that runs on your computer, put the command after --: claude mcp add --transport stdio <name> -- npx -y <package>. Then type /mcp in Claude Code to see whether it connected and to sign in.

MCP (Model Context Protocol) servers give Claude Code new tools: your issue tracker, a database, a design file, a browser. Adding one is one command; the questions come after it. Which projects does it load in? Can the team share it? Where does the API key go?

AIGenerated with AI.

#How do you add a remote MCP server?

HTTP is the transport Claude Code's docs recommend for remote servers:

# Basic syntax
claude mcp add --transport http <name> <url>

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

Some services still offer only SSE, which is deprecated. Recent versions try HTTP first and switch to SSE by themselves; on older ones, use --transport sse.

#How do you add a local MCP server?

A local (stdio) server is a program Claude Code starts on your computer. Everything after -- is the command that runs it:

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

The -- matters. Claude Code's own options (--transport, --env, --scope) go before it; the server's command and its flags go after it, untouched. Without it, a server flag such as --port 8080 is read as one of Claude Code's own.

#Which scope should you use?

claude mcp add takes --scope, and the scope decides where the server loads and who sees it:

A server you use everywhere (a docs search, your notes) belongs in user. A server the whole team needs for this repository belongs in project. Note that "local" here does not mean .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 scope, Claude Code uses one whole entry, in this order: local, then project, then user, then plugin servers and claude.ai connectors. Fields are not merged.

#How do you share a server with your team without sharing the key?

Add it with --scope project, commit the .mcp.json it writes, and put the secret in an environment variable. Claude Code expands ${VAR} and ${VAR:-default} in .mcp.json, in the command, arguments, environment, URL and headers:

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

Each person sets API_KEY on their own machine. Because a cloned repository could add any server, Claude Code asks each person to approve the project's servers before it uses them in an interactive session. claude mcp reset-project-choices resets those answers.

#How do you check, sign in to and remove servers?

A server that needs a login shows up as needing authentication: open /mcp, choose it and sign in in the browser. A claude -p run has no panel for that, so sign in once in an interactive session first.

#What are the errors people hit first?

• "has a "url" but no "type"": in a JSON entry, a server with a url needs "type": "http" (or "sse", "ws"). Without a type, Claude Code reads it as a local command and skips it.
• The server's flags are rejected: the -- before the command is missing.
• A tool's answer is cut off: Claude Code warns when an MCP tool returns more than 10,000 tokens and stops at 25,000 by default. MAX_MCP_OUTPUT_TOKENS=50000 raises the limit.
• Too many servers fill the context: they mostly do not any more. Tool search loads only the tool names at the start and the full definitions when Claude needs them.

#Where can you check this?

• Claude Code docs: connect Claude Code to tools via MCP

#Can you set which project servers are trusted?

Config Studio for Claude Code has the three settings for .mcp.json servers, each explained: trust every server in this project, servers to approve by name, and servers this machine should ignore whatever the project file says. It writes the settings file for you, and nothing changes on your computer until you run its install script yourself.