Claude Code MCP: How to Add and Manage MCP Servers

Claude Code MCP support lets you connect Claude Code to external tools, databases, and APIs through the Model Context Protocol, an open standard for AI-tool integrations. The basic setup is one command: claude mcp add <name> -- npx -y <package> for a local server, or claude mcp add --transport http <name> <url> for a remote one.

What Is MCP in Claude Code?

The Model Context Protocol is an open source standard, introduced by Anthropic in November 2024, that gives language models secure, controlled access to tools and data sources. In Claude Code, each connected MCP server adds tools Claude can call on its own: query a Postgres database, read a Jira ticket, drive a browser, or fetch current library docs, all without you pasting anything into chat.

Servers come in two flavors. Local (stdio) servers run as a process on your machine, usually via npx. Remote servers run as hosted endpoints you reach over HTTP or SSE, like GitHub's at https://api.githubcopilot.com/mcp/ or Sentry's at https://mcp.sentry.dev/mcp. The full reference lives in the official Claude Code MCP docs. If you are deciding between MCP and the plugin system, note that plugins can bundle pre-configured MCP servers; our Claude plugins guide covers that packaging layer.

How to Add MCP Servers: Exact Commands

Claude Code adds MCP servers with the claude mcp add command, and the transport determines the syntax. These forms come straight from the official docs as of July 2026:

# Local stdio server: everything after -- is the server command
claude mcp add <name> -- npx -y <package>

# Example: local filesystem server scoped to two folders
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects

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

# Remote SSE server (legacy transport, still supported)
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Pass environment variables to a stdio server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server

# Pass an auth header to a remote server
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

The -- separator matters for stdio servers: it splits Claude's own options (--transport, --env, --scope) from the command that actually runs the server. For servers that publish raw JSON config instead of a command, claude mcp add-json <name> '<json>' accepts it directly, and the type field takes streamable-http as an alias for http, so configs copied from server docs work unmodified.

Scopes and Config Files: .mcp.json vs ~/.claude.json

Claude Code stores MCP servers in one of three scopes, set with the --scope flag, and the scope decides which file holds the config and who sees the server.

Project scope is the team option: claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp writes a standardized .mcp.json you can commit. For security, Claude Code prompts each person to approve .mcp.json servers before using them, and claude mcp reset-project-choices clears those decisions. The file also supports ${VAR} and ${VAR:-default} expansion, so teams can share config while keeping API keys in each developer's environment.

Listing, Checking, and Removing Servers

Three CLI commands and one slash command cover day-to-day MCP management in Claude Code:

claude mcp list          # all configured servers with connection status
claude mcp get github    # details for one server
claude mcp remove github # delete a server from config
/mcp                     # in-session panel: status, tool counts, OAuth

The /mcp panel is also where authentication happens. When a remote server answers with 401 or 403, Claude Code flags it, and you complete the OAuth flow from the panel; since v2.1.186, claude mcp login <name> runs the same flow straight from your shell, and claude mcp logout <name> clears stored credentials. Servers added via a project's .mcp.json show as "Pending approval" in claude mcp list until you approve them in an interactive session.

Top MCP Servers to Add First

The highest-value first installs are the reference filesystem and memory servers, GitHub's remote server, Context7 for documentation, and Playwright for browser automation. The official modelcontextprotocol/servers repository (87k+ GitHub stars as of July 2026) maintains the reference implementations; the rest are vendor or community projects.

For databases, see our dedicated Postgres MCP server guide, and for the browser side our Playwright MCP breakdown. To search the whole ecosystem without leaving the terminal, Remote OpenClaw ships its own MCP server that queries the directory from inside Claude Code: claude mcp add remoteopenclaw -- npx -y remoteopenclaw. Details are on the MCP server page, or browse the full directory on the web.

Troubleshooting Claude Code MCP Errors

Most Claude Code MCP failures are startup timeouts, missing approvals, or authentication problems. The common fixes:

• Server fails to connect or times out: raise the startup timeout with the MCP_TIMEOUT environment variable, for example MCP_TIMEOUT=10000 claude for 10 seconds. Slow-running tools can get a per-server "timeout" field (in milliseconds) in .mcp.json.
• Project server stuck at "Pending approval": run claude interactively in that folder, accept the workspace trust dialog, and approve the server. A cloned repo cannot approve its own servers.
• Authentication failures: run /mcp and complete the OAuth flow, or claude mcp login <name> from the shell. If you set a headers.Authorization value and the server rejects it, Claude Code reports failure instead of falling back to OAuth; remove the header to use OAuth.
• stdio server dies instantly: test the command by itself first (for example npx -y @modelcontextprotocol/server-memory) to catch missing binaries or bad env vars, then re-add with --env flags.
• Remote server drops mid-session: HTTP and SSE servers auto-reconnect with exponential backoff, up to five attempts; after that, retry manually from /mcp.

Limitations and Tradeoffs

MCP servers can execute code and read data with whatever access you grant them, so treat every third-party server as software you are installing, not just config. Use official vendor servers where they exist, scope filesystem access to specific folders, and keep secrets in environment variables rather than committed .mcp.json files; our guide to securing MCP server connections goes deeper.

There is also a context cost: every connected server's tools consume tokens each turn unless deferred by tool search, so a config with ten servers you rarely use makes every request slower and more expensive. And if all you need is a one-off API call, a plain script Claude runs via Bash is often simpler than standing up a server. Add MCP servers for systems you touch repeatedly, not for everything you can.

Related Guides

• Claude Plugins: What They Are and How to Install Them
• How to Find MCP Servers From Inside Claude Code
• Postgres MCP Server: When Agents Need SQL
• Securing Your MCP Server Connections