How to add an MCP server to Claude Code

Claude Code connects to MCP servers from the command line with claude mcp add, or from a .mcp.json file you commit to your project. This guide covers both, explains the three configuration scopes, and shows how to pass API keys, connect remote servers with OAuth, and check that everything works.

Quick start

Three commands cover most setups:

# A remote server over Streamable HTTP
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A local server that Claude Code starts with npx
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

# Check what is configured and whether each server connects
claude mcp list

Then start claude in your project and run /mcp to see each server's status, sign in where needed, and turn servers on or off.

Add a local (stdio) server

The general form is:

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

Everything after -- is the command that starts the server, passed through unchanged. Everything before it belongs to Claude Code: --transport, --env, --scope and so on. The -- matters when the server's own arguments start with a dash, because without it Claude Code would try to read them as its own flags.

Pass environment variables with --env (or -e), one KEY=value pair each:

claude mcp add -e GITHUB_TOKEN=YOUR_TOKEN -e LOG_LEVEL=info --transport stdio \
  my-server -- npx -y some-mcp-server@1.2.3

One quirk: --env accepts several pairs in a row, so if the server name comes straight after it, Claude Code reads the name as another pair and rejects it. Put a different option, such as --transport stdio, between the last --env and the name, as above.

Pin the package version (@1.2.3) so the server doesn't change under you. The security best practices guide explains why.

On native Windows, if a server fails with spawn npx ENOENT, wrap the command in cmd /c:

claude mcp add --transport stdio my-server -- cmd /c npx -y some-mcp-server

Add a remote (HTTP) server

For a hosted server, use --transport http and the server's URL:

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

Most remote servers use OAuth. After adding one, run /mcp inside Claude Code and follow the browser sign-in, or run claude mcp login <name> from your shell. Claude Code stores and refreshes the token for you.

If a server uses an API key instead, send it as a header:

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

When an Authorization header is set, Claude Code uses it and doesn't fall back to OAuth. The older SSE transport is still available with --transport sse, but it's deprecated, so prefer HTTP wherever a server offers it. The local vs remote guide compares the two transports.

Choose a scope

--scope (or -s) decides where a server is saved and who gets it:

Scope	Loads in	Shared with your team	Stored in
local (default)	The current project only	No	~/.claude.json, under the project's path
project	The current project	Yes, through version control	.mcp.json in the project root
user	All your projects	No	~/.claude.json

Use local for personal experiments and servers with your own credentials. Use project for servers the whole team needs, such as the issue tracker or the staging database. Use user for tools you want everywhere, like a documentation lookup server.

If the same server name exists in more than one scope, local wins over project, and project wins over user. The definitions aren't merged, so the winning entry has to be complete.

The .mcp.json file

claude mcp add --scope project writes to .mcp.json, and you can also edit it by hand:

{
  "mcpServers": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp"
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": { "DB_URL": "${DB_URL}" }
    }
  }
}

A few rules:

• Always set type on remote entries. An entry with a url but no type is treated as stdio, which is a configuration error.
• Use variables for secrets. Claude Code expands ${VAR} and ${VAR:-default} in command, args, env, url and headers. Each teammate sets the variable in their own shell, and the secret never lands in Git.
• Expect an approval prompt. In an interactive session, Claude Code asks before using servers from a project's .mcp.json. To be asked again, run claude mcp reset-project-choices.

Add from JSON, or import from Claude Desktop

If a README gives you a JSON config, add it in one step:

claude mcp add-json weather '{"type":"stdio","command":"npx","args":["-y","weather-mcp-server"]}'

If you already set servers up in Claude Desktop, claude mcp add-from-claude-desktop opens a picker and imports the ones you choose. It works on macOS and on Windows Subsystem for Linux. Add --scope user to make them available in every project.

Manage your servers

claude mcp list            # every server and its health
claude mcp get <name>      # details for one server, including errors
claude mcp remove <name>   # delete it (add --scope if the name is ambiguous)
claude mcp logout <name>   # revoke stored OAuth credentials, where supported

Removing a server deletes its stored OAuth tokens locally but doesn't revoke them. Run claude mcp logout first if you want the grant revoked too.

Use what the server provides

• Tools are called by Claude when a task needs them. Claude Code asks for permission first unless you've allowed the tool.
• Resources can be referenced with @. Type @ in your prompt and they appear alongside files.
• Prompts become slash commands, listed as /servername:promptname (MCP). Typing /mcp__servername__promptname also runs them.

Claude Code uses tool search by default. Only tool names and server instructions load when a session starts, and full tool definitions load when Claude needs them, so adding servers costs little context.

If a server won't connect

• It times out on first start. npx and uvx may be downloading the package. Run the command once in a terminal, or raise the startup timeout with MCP_TIMEOUT=60000 claude.
• It connects with no tools. A required environment variable, often the API key, is probably missing. claude mcp list reports missing variables.
• Large tool results get cut off. Claude Code warns when a result passes 10,000 tokens and caps output at 25,000 tokens by default. Raise the cap with MAX_MCP_OUTPUT_TOKENS.

For anything else, the troubleshooting guide walks through the common failures. To find servers worth adding, browse the directory: every server page has a copy-ready Claude Code command, and the Claude Code client page lists servers you can install in it.