Claude Code MCP: Add, Configure and Manage MCP Servers

How Claude Code Connects to MCP Servers

Claude Code connects to MCP servers through the claude mcp add command: use --transport http for a remote server URL, or put a local launch command after -- for a stdio server. Each server is saved in one of three scopes (local, project or user), and you check, sign in to and reconnect servers from the /mcp menu inside a session.

The rest of this guide covers every part of that sentence, with commands checked against the official Claude Code MCP documentation. If you just want something to connect, browse the MCP server directory first.

Quick Reference

Step 1: Choose a Transport

MCP servers come in two broad shapes, and Claude Code supports both.

Remote HTTP servers (recommended)

Most hosted servers expose a Streamable HTTP endpoint. Pass the URL with --transport http:

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

If the server takes an API key instead of OAuth, send it as a header:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

That second example is the GitHub MCP server with a fine-grained personal access token. Note that claude mcp add saves the config without validating credentials, so a wrong token only shows up later as a failed connection.

Remote SSE servers (deprecated)

Older servers still use Server-Sent Events. The SSE transport is deprecated in the MCP spec, but Claude Code still supports it:

claude mcp add --transport sse asana https://mcp.asana.com/sse

According to the docs, recent versions of Claude Code also fall back to SSE automatically when you use --transport http against an SSE-only endpoint.

Local stdio servers

A stdio server is a process Claude Code launches on your machine, typically via npx, uvx or a binary. Everything after the -- separator is passed to the server unchanged:

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

Three rules prevent most stdio mistakes:

• Claude Code's own options (--transport, --env, --scope, --header) go before the -- separator.
• Flags meant for the server (like -y for npx or --port 8080) go after --.
• --env accepts several KEY=value pairs. If the server name comes directly after --env, the CLI reads the name as another pair and rejects it, so put another option such as --transport stdio in between.

Short forms exist too: -t for --transport, -e for --env, -H for --header, and -s for --scope.

Step 2: Pick a Scope

Every server you add lives in one scope. The default is local.

Guidelines that hold up in practice:

• local for personal experiments and anything with your own credentials.
• project for servers the whole team should get when they clone the repo, such as a docs server or the Playwright MCP server for UI testing.
• user for tools you want everywhere, such as Context7 for up-to-date library docs.

When the same server name exists in more than one scope, local wins over project, and project wins over user. The whole entry from the winning scope is used; fields are not merged.

Step 3: Share Servers With .mcp.json

Adding a server with --scope project writes a file like this to your project root:

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

You can also edit .mcp.json by hand and commit it. Two details matter:

• An entry with a url but no type is read as stdio and fails. Always set "type": "http" (or "sse") for remote servers.
• Claude Code asks for approval before using project servers in an interactive session, and a cloned repo cannot approve its own servers. Until you approve, claude mcp list shows the server as pending. To reset your approvals, run claude mcp reset-project-choices.

Keep secrets out of git with environment variables

.mcp.json supports variable expansion 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} expands to the variable's value and ${VAR:-default} falls back to a default. If a variable is unset and has no default, the literal text stays in the config and claude mcp list warns you. For more on handling tokens safely, see our MCP security best practices.

Step 4: Authenticate With OAuth

Many hosted servers (Notion, Sentry, Linear and others) use OAuth instead of static keys. Add the server, then sign in from inside Claude Code:

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

Start claude, type /mcp, select the server and complete the login in your browser. You can also sign in from the shell with claude mcp login sentry (add --no-browser on a headless machine) and clear stored tokens with claude mcp logout sentry.

A few limits to know:

• Non-interactive runs (claude -p) cannot complete OAuth. Sign in once from an interactive session first.
• Servers that need a pre-registered OAuth app accept --client-id, --client-secret and --callback-port at add time.

The protocol side of this flow is explained in MCP authentication and OAuth.

Step 5: Add a Server From Someone Else's Instructions

Many READMEs only show a Claude Desktop or Cursor config. Convert them like this:

• A URL means a remote server: claude mcp add --transport http name URL.
• A launch command like npx -y @example/mcp-server means stdio: claude mcp add name -- npx -y @example/mcp-server.
• An mcpServers JSON block: pass the inner object (not the wrapper) to add-json.

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

add-json also accepts --scope user or --scope project.

Import from Claude Desktop

If your servers already work in Claude Desktop, import them:

claude mcp add-from-claude-desktop

An interactive picker lets you choose which servers to import. This works on macOS and WSL only. Server names may contain only letters, numbers, hyphens and underscores, so a Desktop server whose name has a space is skipped, and duplicate names get a suffix such as server_1.

Managing Servers Day to Day

claude mcp list          # every server plus a health status
claude mcp get notion    # details for one server
claude mcp remove notion # delete it (and its stored OAuth tokens)

Inside a session, /mcp shows each server's status and tools and lets you reconnect, re-authenticate or disable a server without deleting it. Statuses you will see include ✔ Connected, ! Needs authentication, ✘ Failed to connect and ⏸ Pending approval.

Context usage and tool search

Tool search is on by default: Claude Code loads only tool names at startup and fetches full definitions when Claude needs them, so adding servers has little effect on your context window. To load a small, always-needed server upfront, set "alwaysLoad": true on its entry. To turn deferral off entirely, start with ENABLE_TOOL_SEARCH=false claude. For background on how clients find tools, read MCP tool discovery.

Resources and prompts

Servers can expose resources you reference with @, for example @github:issue://123, and prompts that appear as slash commands in the form /mcp__servername__promptname. If you are unsure what a server exposes, see MCP resources vs tools.

Troubleshooting

When a stdio server crashes, test its command directly in your terminal first. When a remote server misbehaves, the MCP Inspector shows exactly what it returns. Also note that stdio servers are not reconnected automatically; use /mcp to reconnect.

Recommended MCP Servers for Claude Code

For the browser server, follow the dedicated Playwright MCP Claude Code setup guide.

Next Steps

Pick one server you will actually use this week, add it at local scope, and confirm it shows ✔ Connected in /mcp before adding more. When it earns its place, move it to project scope so your team gets it too. To find more, browse the MCP server directory or filter by category.