Claude Code MCP: add servers, scopes and commands

What is MCP in Claude Code, and when do you need it?

The Model Context Protocol (MCP) is an open standard for connecting AI tools to outside systems. According to the official MCP page, MCP servers give Claude Code access to your tools, databases and APIs. The docs' rule of thumb: connect a server when you find yourself copying data into chat from another tool, such as an issue tracker or a monitoring dashboard. Once connected, Claude can read and act on that system directly instead of working from what you paste.

Examples from the docs include implementing a feature from a JIRA issue and opening a GitHub PR, querying a PostgreSQL database, checking Sentry for errors, and updating an email template from Figma designs. If the system already has a command-line tool, the best practices page says that is usually the easiest way in; with gh installed and signed in, Claude opens pull requests without any setup. MCP is for systems without a CLI.

How do you add an MCP server to Claude Code?

You add servers from your shell with claude mcp add. The right form depends on where the server runs.

The docs call HTTP the most widely supported transport for cloud-based services. SSE is deprecated: on Claude Code v2.1.265 or later, the HTTP command tries HTTP first and switches to SSE if the server does not accept it, so you rarely need --transport sse. WebSocket cannot be added with the --transport flag; use add-json or .mcp.json.

For stdio servers, the -- (double dash) separates Claude's own options such as --transport, --env and --scope from the command that runs the server. Everything after it is passed through untouched. Without it, Claude Code would read a server flag such as --port as its own. One more quirk: --env takes several KEY=value pairs, so place at least one other option (for example --transport stdio) between --env and the server name, or the name is read as another pair.

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remote HTTP server with a header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local stdio server with an environment variable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

# Any server, from a JSON definition
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

A command that prints an Added ... line only means the configuration was written. The docs say claude mcp add does not validate credentials, so a placeholder token is accepted and the server fails later. Run claude mcp get <name> or /mcp to confirm it actually connected.

What are the MCP scopes: local, project and user?

Choose with --scope local, --scope project or --scope user. Use local scope for personal or experimental servers and ones with credentials you do not want in version control. Use project scope for servers the whole team needs, and commit the file. Use user scope for tools you want everywhere.

# local (default): only you, only this project
claude mcp add --transport http stripe https://mcp.stripe.com

# project: written to .mcp.json so the team gets it
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# user: you, every project
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

When the same server name exists in more than one place, Claude Code connects once, using the highest-precedence definition and not merging fields. The order is local, then project, then user, then plugin-provided servers, then claude.ai connectors. If you define one name in several scopes with different endpoints, claude mcp list and /mcp warn you; remove the extras with claude mcp remove <name> --scope <scope>.

Project scope has a safety step. Claude Code asks for approval in interactive sessions before using servers from a .mcp.json file, and claude mcp reset-project-choices resets those answers. A cloned repository cannot approve its own servers: approvals committed to its own .claude/settings.json are ignored until you trust the workspace, so the server stays at Pending approval. In claude -p runs, though, Claude Code cannot show the prompt and loads project servers without asking, so use --strict-mcp-config or disabledMcpjsonServers there if you need to keep one out.

Which claude mcp commands should you know?

Server names added with claude mcp may contain only letters, numbers, hyphens and underscores. Reserved names such as workspace and claude-in-chrome are rejected. In a session, you can turn a server off without deleting it from the /mcp panel, which records the choice per project; the docs recommend that because connected servers add their tool names and instructions to your context even when you are not using them.

What do working MCP configs look like?

Three examples, each from patterns the official docs show. Replace the placeholders with your own values.

# Create a fine-grained personal access token in your GitHub settings first.
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

# Then in a session:
#   Review PR #456 and suggest improvements
#   Create a new issue for the bug we just found
#   Show me all open PRs assigned to me

# Use a read-only database user so queries cannot modify data.
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# Then in a session:
#   Show me the schema for the orders table
#   Find customers who haven't made a purchase in 90 days

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

The third example is how teams share a config without sharing secrets. Claude Code expands ${VAR} and ${VAR:-default} in command, args, env, url and headers. If a referenced variable is unset and has no default, the config still loads with the literal ${VAR} text and a warning appears in claude mcp list. One trap: in a remote server's url and headers, Claude Code reads its own and your cloud provider's credentials as empty, such as ANTHROPIC_API_KEY or NPM_TOKEN, so Bearer ${ANTHROPIC_AUTH_TOKEN} sends no token. Copy the secret into a variable with your own name instead.

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

# The same server from the command line:
claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

That last example matters when a server's setup guide is written for Claude Desktop or Cursor. Pass add-json the object inside mcpServers, not the wrapper. A url entry with no type is an error, because an entry with no type is read as stdio: add "type": "http", "sse" or "ws". The docs list streamable-http as an accepted alias for http in JSON.

How do you sign in to a remote MCP server?

Many cloud servers use OAuth 2.0. Claude Code marks a server as needing authentication when it answers with 401 or 403. To sign in:

1. Add the server, for example claude mcp add --transport http sentry https://mcp.sentry.dev/mcp.
2. In a session, run /mcp and follow the steps in your browser. Or run claude mcp login sentry from your shell.
3. If no browser is available (an SSH session, say), the login command prints the URL; open it elsewhere and paste the redirect URL back. Pass --no-browser to force that.

Tokens are stored and refreshed automatically. Use Clear authentication in the /mcp menu, or claude mcp logout <name>, to remove them. If you configured an Authorization header and the server rejects it, Claude Code reports a failed connection instead of falling back to OAuth, so fix the token or remove the header. In claude -p runs there is no /mcp panel, so complete the sign-in in an interactive session first.

How does Claude use MCP servers once they are connected?

• Tools. Claude calls a server's tools like built-in ones, subject to your permission rules. By default tool definitions are deferred and found on demand through tool search, so only tool names and server instructions load at session start. Set ENABLE_TOOL_SEARCH=false to load everything upfront.
• Resources. Type @ to see resources from connected servers, then reference one as @server:protocol://resource/path, for example @github:issue://123.
• Prompts. Servers can expose prompts as commands, listed as /servername:promptname (MCP). Typing /mcp__servername__promptname also runs one, with arguments separated by spaces.
• Output limits. Claude Code warns when a tool's output passes 10,000 tokens. The default maximum is 25,000 tokens; raise it with the MAX_MCP_OUTPUT_TOKENS environment variable. Results over the limit are saved to a file and Claude is given the path.
• Subagents. A subagent inherits MCP tools by default; scope or withhold them with the mcpServers and disallowedTools fields (see the subagents guide).

Servers can also arrive through plugins, which can bundle them, or from your claude.ai account: connectors you added there are automatically available when you are logged in with that account. Permission rules for MCP tools follow the same system as everything else; see the permissions guide.

Why won't an MCP server connect?

Claude Code retries a dropped remote server up to five times with exponential backoff, and /mcp reconnect all retries every server that failed or needs authentication. If you are building something that needs several servers, see the guide to building an app with Claude Code. A docs-grounded assistant such as An agent that answers from your docs and shuts up otherwise, posted on the board, is the kind of project where a docs or database server pays off quickly; more are on the AI agents ideas page.