How to add an MCP server to Claude Code: claude mcp add, scopes and fixes

The short version

Add a server from your terminal with claude mcp add, choose where it should live with --scope, and confirm it connected with claude mcp list. Remote servers use the HTTP transport and a URL; local servers run as a command after a -- separator. Everything else on this page is about getting those three steps right the first time, and about what to check when a server shows up as failed.

Adding a remote server (HTTP)

Most hosted MCP servers speak HTTP, which Claude Code's documentation recommends for remote servers:

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

If the server authenticates with a static token, pass it as a header:

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

If it uses OAuth instead, add it without a header and sign in afterwards: run /mcp inside Claude Code, pick the server and choose sign in, or run claude mcp login <name> from the terminal. The SSE transport still works but is deprecated; prefer HTTP where a server offers it.

Adding a local server (stdio)

A local server is a program Claude Code starts for you. Everything after the -- is passed to that program untouched, which is why the separator matters — without it, the server's own flags get read as Claude Code's:

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

On Windows, npx servers need to run through cmd /c:

claude mcp add --transport stdio weather -- cmd /c "npx -y weather-server"

Adding a server from JSON, or from Claude Desktop

When a vendor's documentation gives you a JSON configuration rather than a command, pass it whole with claude mcp add-json, which also takes --scope:

claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp"}'

It is also the only way to configure a WebSocket server. If your servers already live in Claude Desktop, claude mcp add-from-claude-desktop imports them. One catch: names added through claude mcp may contain only letters, numbers, hyphens and underscores, and Claude Desktop has no such rule, so a Desktop server whose name contains a space can't be imported until you rename it.

Choosing a scope

--scope decides who else gets the server and where it is stored. local (the default) keeps it private to you in the current project. project writes it to a .mcp.json file at the project root, so everyone who clones the repository gets it — and Claude Code asks each of them to approve it before first use. user makes it available to you in every project. The distinction matters most for credentials; see MCP scopes in Claude Code for sharing a server without committing a secret.

Checking that it worked

claude mcp list        # every server, with its health
claude mcp get notion  # one server's configuration
claude mcp remove notion

A healthy server shows as connected. The other states each point at a different fix: failed to connect, needs authentication, pending approval for a project-scoped server, or disabled for this project in /mcp. When Claude Code can't connect to an MCP server walks through each one.

Scope the server's own access, not just its location

An MCP server is code running with whatever access its credentials grant, and Claude Code calls its tools the same way it calls any other. A database server pointed at production with write access turns every session into one that can modify production data. Prefer read-only credentials and a staging environment wherever the server allows, and let Claude Code's permission system require confirmation for a server's write tools until you have watched them behave.

Keeping large tool results in check

A tool that returns a very large result fills the context window fast. Claude Code warns when a single tool's output crosses its threshold, and beyond its ceiling saves the result to a file and hands Claude the path instead. The ceiling is set by the MAX_MCP_OUTPUT_TOKENS environment variable; a server that slows down at startup can be given more time with MCP_TIMEOUT.

When you don't need a server

Not every integration needs MCP. If Claude Code only has to call a REST API a handful of times, a short script it runs is simpler to reason about and debug. MCP earns its setup when the same tools are reused across many sessions and many people.

If you drive Claude Code from a terminal multiplexer or an editor whose keybindings you are still learning, AltPlusCtrl keeps a practice-driven shortcut reference for exactly those tools.