Claude Code MCP Servers: Setup, Scopes and Picks

To add an MCP server to Claude Code, run claude mcp add --transport http <name> <url> for a remote server, or claude mcp add <name> -- <command> for a local one. Pick a scope with --scope local, project or user, check it with claude mcp list or /mcp, and remove it with claude mcp remove <name>. We checked Anthropic's MCP docs and each server's repo on 31 October 2026.

Quick facts

The four ways to add a server

1. Remote HTTP: the recommended route

Claude Code's docs call HTTP the recommended option and the most widely supported transport for cloud services.

# basic form
claude mcp add --transport http <name> <url>

# a real example from the docs
claude mcp add --transport http notion https://mcp.notion.com/mcp

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

In JSON, the type field accepts streamable-http as an alias for http, so a block copied from server docs works unchanged. A JSON entry with a url but no type is an error, because Claude Code reads an entry with no type as stdio. It skips that server and reports MCP server "<name>" has a "url" but no "type".

2. Remote SSE: only if you must

The docs mark SSE as deprecated. Use the HTTP command, and on Claude Code v2.1.265 or later it tries HTTP first and switches to SSE if the server does not accept it. On earlier versions, or to force SSE, use --transport sse.

3. Local stdio

Stdio servers run as a process on your machine.

claude mcp add [options] <name> -- <command> [args...]

# example from the docs
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

The double dash matters. Everything before -- is for Claude Code (--transport, --env, --scope), and everything after it runs untouched. Without it, Claude Code would try to parse the server's own flags as its own. One more gotcha from the docs: --env takes several KEY=value pairs, so if the server name directly follows it the CLI reads the name as another pair. Put another option, such as --transport stdio, between them.

Claude Code sets CLAUDE_PROJECT_DIR in the spawned server's environment, so a server can find the project root without relying on the working directory.

4. WebSocket

For remote servers that push events to Claude. Add it with claude mcp add-json and "type":"ws". Use HTTP unless your server needs a persistent two-way connection.

Pasting a block from another client

Most install guides are written for Claude Desktop or Cursor. Claude Code's docs give a rule: if the guide shows a URL, use the HTTP command; if it shows a launch command such as npx -y @example/mcp-server, use the stdio form. Or pass the JSON straight in:

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

claude mcp add-from-claude-desktop imports servers you already set up in Claude Desktop.

Scopes: who sees the server

claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

If the same server is defined in more than one place, Claude Code connects once, using the highest-precedence definition: local, then project, then user, then plugin-provided, then claude.ai connectors. The whole entry from that source is used; fields are not merged.

A committed .mcp.json

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    }
  }
}

Claude Code expands ${VAR} and ${VAR:-default} in command, args, env, url and headers. That is how you share a config without sharing a secret: everyone sets GITHUB_PAT in their own shell.

Project-scoped servers need approval. In an interactive session Claude Code asks before using a server from .mcp.json, and a cloned repository cannot approve its own servers. claude mcp reset-project-choices clears your past approvals. Be aware of the exceptions: in claude -p runs, Agent SDK sessions and cloud sessions, the prompt cannot be shown and project-scoped servers load without asking. To keep one out anyway, use disabledMcpjsonServers, exclude project settings, or start with --strict-mcp-config.

Manage what you have

claude mcp list          # health status per server
claude mcp get notion    # details for one
claude mcp remove notion # remove

claude mcp list prints statuses such as Connected, Needs authentication and Failed to connect. It also prints configuration states that involve no connection attempt: Pending approval, Rejected, Disabled for this project and Blocked by enterprise managed policy.

In a session, /mcp opens the panel where you can reconnect, enable or disable a server, or sign in. Toggling a server off keeps its config and records your choice per project. Removing a remote server also deletes the OAuth tokens Claude Code stored for it, though it does not revoke them at the authorization server.

Authentication

For remote servers that use OAuth, run /mcp and follow the browser flow, or sign in from a shell:

claude mcp login sentry
claude mcp login sentry --no-browser   # over SSH

Two flags cover servers with unusual OAuth setups. --callback-port fixes the redirect port to match a pre-registered URI, and --client-id with --client-secret supplies pre-configured credentials when a server does not support dynamic client registration.

You can pin scopes. The docs use Slack as the example:

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": { "scopes": "channels:read chat:write search:read" }
    }
  }
}

That is the supported way to restrict a server to a subset your security team approved. For static tokens, use --header, and for rotating ones the docs describe dynamic headers.

Keep context and output under control

Tool search. On by default. MCP tool definitions are deferred, so only tool names and server instructions load at session start. The docs say there is no fixed per-server tool cap; the practical limit is your context budget. It applies to Opus 4, Sonnet 4, Haiku 4.5 and later models. Control it with ENABLE_TOOL_SEARCH: true, false, auto (load tools upfront while their definitions total under 10% of the context window), or auto:N for another percentage.

Output limits. A warning appears when a tool result passes 10,000 tokens. The default maximum is 25,000, adjustable:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Results over the limit are saved to a file and replaced in the conversation by its path. Text results over 50,000 characters are saved the same way. HTTP and SSE responses over 16 MiB fail.

Timeouts. MCP_TIMEOUT sets the server startup timeout, for example MCP_TIMEOUT=10000 claude. Slow npx starts are the usual reason to raise it.

Long calls. The docs describe automatic backgrounding of long tool calls and support for MCP tasks that run on the server.

Beyond tools: resources, prompts and more

• Resources. Type @ to see resources from connected servers next to files. Format: @server:protocol://resource/path, for example @github:issue://123.
• Prompts as commands. A server's prompts appear as /mcp__servername__promptname, such as /mcp__github__pr_review 456. Arguments are split on whitespace.
• Channels. A research-preview feature lets an MCP server push messages into a running session.
• Elicitation. Servers can ask you questions mid-task; Claude Code handles those requests.
• Per-tool approval. A server author can mark a tool so Claude Code asks every time, even in acceptEdits, auto and bypassPermissions modes.
• Claude Code as a server. claude mcp serve starts Claude Code as a stdio MCP server for other apps.
• claude.ai connectors. Connectors you enable for your account can show up in Claude Code; you can disable them there.
• Plugin servers. Plugins can bundle MCP servers, which then load wherever the plugin is enabled.

A starter set for Claude Code

Our picks, with the command for each. Detail and risks are on each page.

For a ranked view see best MCP servers, and for the format in other agents see the MCP servers hub. The Context7 line above omits a key; add --header "Authorization: Bearer YOUR_API_KEY" for higher limits.

Security habits for Claude Code

1. Trust the source. Claude Code's docs say to verify you trust each server and that fetching external content raises prompt injection risk.
2. Scope tokens. Fine-grained, one repository, one database role.
3. Start read-only. Many servers have a read-only flag.
4. Keep secrets out of `.mcp.json`. Use ${VAR} expansion, OAuth or --scope local.
5. Do not rubber-stamp project servers. A repository that ships a .mcp.json is asking you to run its commands.
6. Use permission rules. MCP tools appear in /permissions like any tool, so you can allow or deny them by name.
7. Teams can lock it down. Managed MCP configuration deploys a fixed set and restricts the rest, using a managed-mcp.json file and allow and deny lists.
8. Avoid bypass modes. --dangerously-skip-permissions plus a write-capable server plus untrusted content is the combination to avoid.

Sharing servers with a team safely

A project-scoped .mcp.json file in the repository root is how a team shares servers, and it is where secrets leak if you are careless. The docs support environment variable expansion in that file, so the file can be committed while each person's key stays on their own machine. You can reference a variable in a server's command, args, env, url or headers, as ${VAR} or with a fallback as ${VAR:-default}.

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

The URL and the key name above are placeholders. Commit this file, and tell teammates to export API_KEY in their shell or a local, ignored file. Two behaviours from the docs are worth knowing. A variable that is not set and has no default produces a warning in claude mcp list and /mcp, and the server still loads with the ${VAR} text unexpanded, so a missing key looks like an authentication failure and not a typo. And for a remote server's url and headers, some credential variables read as empty with no warning, so test the connection after setting one.

Trust works in your favour

A cloned repository cannot approve its own servers. The docs say that project-scoped servers need your approval, and that settings which would auto-approve them, enableAllProjectMcpServers or enabledMcpjsonServers, are ignored in an untrusted folder when committed in the project's .claude/settings.json. A server stays at pending approval until you open the workspace, accept the trust dialog and approve it. That blocks the obvious attack, where a repository ships an MCP server definition that runs on checkout. It does not replace reading the file. When you clone an unfamiliar project, read .mcp.json before you accept the trust dialog, and look at the command of every stdio entry, since that is code that will run.

What administrators can add

Organizations have more levers. The docs describe managed MCP configuration, where an administrator can provide servers for every user and can restrict which servers are allowed. A server your organization provides ranks above the others, so a user cannot replace it with their own. Servers blocked by an allow list or deny list are hidden from claude mcp list rather than shown as blocked, which can confuse a user who cannot find a server a colleague has. The message to give them is to ask the administrator which policy applies. The --strict-mcp-config flag goes the other way for single sessions: Claude Code then uses only the servers you pass with --mcp-config. That suits scripted or CI jobs, where you want a known set of tools and no interactive prompts.

A rollout plan for a team

1. Start with one shared read-only server and one owner who answers questions about it.
2. Put the definition in `.mcp.json` with variable expansion, and add a README line that says which variables to set.
3. Document the approval step. New teammates see a pending approval, and a line in your onboarding saves a support thread.
4. Review changes to `.mcp.json` in pull requests, since each edit changes what runs on every developer's machine.
5. Agree on scopes. Project scope for what the team shares, local scope for experiments, and user scope for a personal helper that follows you across projects.
6. Check `claude mcp list` after each merge that touches the file, so a broken definition is noticed in minutes.
7. Decide the exit. Name who removes a server when its owner leaves or its vendor changes terms.

Related pages: the MCP server list for candidates, best MCP servers for a shortlist, and how to build an MCP server when nothing off the shelf fits.

Troubleshooting

Run claude --debug='mcp,startup' for logs. The docs also have a debug-your-config page that covers /context, /doctor and /hooks.

Our take

We read the documentation and tested none of these servers, so treat this as a guide, not a review.

Claude Code's MCP support is thorough. Three scopes, an approval step, ${VAR} expansion, scope-pinning for OAuth and a managed policy layer cover most of what a team needs. The weakest part is not the tool but the habit of copying a command from a blog post. Check the transport, check the scope, and read what the server can do before you press enter.

Our default: user scope for read-only helpers you want everywhere (Context7), project scope for what the whole team needs (GitHub in read-only mode, Playwright), and local scope for anything with a personal token. Commit .mcp.json with variable references only.

Because tool search is on, adding a fifth server costs less than it used to. That is not a reason to add it. Every server is still another thing that can read your data or act in your name.

Frequently asked questions

How do I add an MCP server to Claude Code? claude mcp add --transport http <name> <url> or claude mcp add <name> -- <command>.

Where does Claude Code store MCP servers? ~/.claude.json for local and user scope, .mcp.json for project scope.

How do I see which servers are connected? claude mcp list or /mcp.

Do many MCP servers slow Claude Code down? Tool search defers tool definitions by default, so the impact on context is small.

Can Claude Code be an MCP server itself? Yes, with claude mcp serve.

*Product names are used descriptively. We are not affiliated with Anthropic or any server vendor named here.*