How to connect Claude Code MCP servers and keep them safe

Claude Code MCP servers are added with claude mcp add, which takes a name plus a URL for a remote server or a launch command for a local one. Each server lives in one of three scopes: local (you, this project), project (shared through a .mcp.json file) or user (you, every project). Before adding any server, check who runs it, what it can reach and what credentials it gets.

What an MCP server adds to Claude Code

The Model Context Protocol (opens in a new tab) is an open standard for connecting AI applications to outside systems. A server exposes tools, resources and prompts. Once a server is connected, Claude Code can call its tools directly instead of working from text you paste into the chat.

The Claude Code docs give examples such as reading an issue from a tracker, checking error monitoring data, or querying a PostgreSQL database. Resources from a server can be referenced in a prompt, and a server's prompts show up as commands.

Adding a server with the claude mcp command

The Claude Code MCP reference (opens in a new tab) lists three ways to add a server from the command line. Server names may contain only letters, numbers, hyphens (-) and underscore characters (_).

Remote HTTP servers

HTTP is the transport the docs recommend for remote servers:

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

To send a static token, add a header:

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

The SSE transport is deprecated. From v2.1.265, --transport http tries HTTP first and falls back to SSE when a server only speaks SSE. On older versions, pass --transport sse for those servers.

Local stdio servers

A stdio server is a process that Claude Code starts on your machine. Everything after -- is the command that runs it, passed through untouched:

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

Without the --, Claude Code tries to read the server's own flags as its options. Keep at least one other option between --env and the server name, or the CLI parses the name as another KEY=value pair and rejects it. Claude Code sets CLAUDE_PROJECT_DIR in the server's environment so the server can find the project root.

From a JSON block or Claude Desktop

Setup instructions written for another client often give an mcpServers JSON block. Pass the object inside mcpServers (not the wrapper) to claude mcp add-json:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

An entry with a url but no type fails, because Claude Code reads a missing type as stdio. Add "type": "http", "sse" or "ws". To copy servers you already set up in Claude Desktop, run claude mcp add-from-claude-desktop. The import works only on macOS and WSL.

Local, project and user scopes for Claude Code MCP servers

The --scope flag decides where a server is stored and who gets it. Local is the default.

"Local" here differs from local settings. Local MCP servers sit in ~/.claude.json in your home directory, while local settings use .claude/settings.local.json inside the project.

When the same server name appears in several places, Claude Code connects once and uses the whole entry from the highest-ranked source, without merging fields. The order is local, then project, then user, then plugin-provided servers, then claude.ai connectors.

Which scope to pick

Sharing servers with a team through .mcp.json

claude mcp add --scope project creates or updates .mcp.json at the project root. Commit that file and everyone who clones the repo gets the same server list. A typical file looks like this (illustrative names and URLs):

{
  "mcpServers": {
    "tracker": {
      "type": "http",
      "url": "${TRACKER_URL:-https://mcp.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${TRACKER_TOKEN}"
      }
    },
    "db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${READONLY_DSN}"]
    }
  }
}

.mcp.json supports ${VAR} and ${VAR:-default} expansion in command, args, env, url and headers. That keeps each person's tokens in their own environment instead of the repo. If a variable is unset and has no default, the server still loads, with the raw ${VAR} text and a warning in claude mcp list.

One guard to know: in a remote server's url and headers, Claude Code reads its own and your cloud provider's credentials (such as ANTHROPIC_API_KEY or AWS_BEARER_TOKEN_BEDROCK) as empty. A shared .mcp.json cannot send those secrets to a server it names. Copy a credential into a variable with your own name if a server really needs it.

How project servers get approved

In an interactive session, Claude Code asks for approval before it uses servers from .mcp.json. Run claude mcp reset-project-choices to clear those choices. Since v2.1.196, a cloned repository cannot approve its own servers: an enableAllProjectMcpServers or enabledMcpjsonServers entry committed to the project's .claude/settings.json is ignored until you accept the workspace trust dialog.

The prompt does not appear everywhere. In claude -p runs, Agent SDK sessions and cloud sessions, Claude Code loads project servers without asking. To keep a server out in every mode, list it in the disabledMcpjsonServers setting.

Remote servers and authentication

Many hosted servers use OAuth 2.0. Add the server, then run /mcp inside Claude Code and finish the sign-in in your browser:

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

You can also sign in from the shell with claude mcp login sentry and clear stored credentials with claude mcp logout sentry. On a machine without a browser, such as over SSH, claude mcp login prints the authorization URL so you can open it elsewhere. --no-browser forces that behavior.

Some servers need a redirect URI registered in advance. By default Claude Code picks a random callback port, and --callback-port fixes it so it matches http://localhost:PORT/callback. Servers without dynamic client registration need your own OAuth app: pass --client-id, and --client-secret prompts for the secret with masked input.

Tokens are refreshed automatically. Choosing "Clear authentication" in the /mcp menu revokes access, and removing a remote server also deletes its stored tokens and client registration. If you set an Authorization header yourself and the server rejects it, Claude Code reports a failed connection instead of falling back to OAuth.

Checking and removing servers

claude mcp list            # every server, with a health status
claude mcp get notion      # details for one server
claude mcp remove notion   # delete it

claude mcp list shows statuses such as ✔ Connected, ! Needs authentication and ✘ Failed to connect. A project server waiting on approval shows ⏸ Pending approval. If the same name exists in two scopes with different endpoints, remove the one you do not want with claude mcp remove <name> --scope <scope>.

To pause a server without deleting it, toggle it off in the /mcp panel. Claude Code records the choice per project in ~/.claude.json.

Large tool results are capped. Claude Code warns when one MCP tool's output passes 10,000 tokens, and the default maximum is 25,000 tokens. Set MAX_MCP_OUTPUT_TOKENS to change it. Results over the limit are saved to a file, and Claude reads that file when it needs the content.

What to check before trusting an MCP server

The Claude Code security docs (opens in a new tab) say Anthropic reviews connectors against its listing criteria before adding them to the Anthropic Directory, but does not security-audit or manage any MCP server. The docs recommend writing your own servers or using ones from providers you trust. Servers that fetch outside content can also expose you to prompt injection.

Copy this checklist into your team's onboarding notes:

• ☐To do: Who publishes the server, and is the source code or package page public?
• ☐To do: Is it remote (code runs on someone else's machine) or stdio (code runs on yours, with your account's access)?
• ☐To do: For an npx -y or uvx command, is the package pinned to a version you have read?
• ☐To do: Which credentials does it get? Prefer a fine-grained or read-only token, such as a read-only database user.
• ☐To do: Does it read web pages, email, tickets or other text written by outsiders? That text reaches the model.
• ☐To do: Which of its tools write, delete or send? Those should ask for approval every time.
• ☐To do: Is it going into .mcp.json, where everyone who clones the repo will be asked to approve it?

Permission rules give you control per tool. In the Claude Code permissions settings (opens in a new tab), mcp__github matches every tool from the github server, mcp__github__* does the same with a wildcard, and mcp__github__get_issue matches one tool. Deny rules accept mcp__* to block every MCP tool. Allow globs must start with a literal mcp__<server>__ prefix, so an allow rule always names a specific server.

Remember that .mcp.json is only part of the picture. Servers from your local and user scopes, plugins and claude.ai connectors also load, so reviewing the repo file does not show everything a session can reach. Run /mcp to see the full list in a live session.