Claude MCP Add Command: How to Install MCP Servers in Claude Code

claude mcp add is the single command that connects Claude Code to external tools. Run it once for a server, and every session you open in that project — or across all projects — can use the tools the server exposes. This guide covers the full syntax, the three scope options with their corresponding config files, how to set up stdio and HTTP transports, Windows-specific behavior, and how to route tool execution through Novita’s LLM API and Agent Sandbox.

What claude mcp add does

When you run claude mcp add, Claude Code writes a server definition to a configuration file. At session start, it reads that definition, launches or connects to the server, and queries it for its tool list. From that point on, Claude can call any of those tools during the conversation — no further setup needed.

The command works the same on macOS, Linux, Windows PowerShell, and Windows Command Prompt. The only thing that changes across platforms is how paths are formatted and where the config files live.

---

Prerequisites

Before adding any MCP server, confirm you have:

• Claude Code installed and authenticated. Verify with claude --version.
• Node.js 18 or later for servers that use npx. Download from nodejs.org.
• Python 3.10 or later if the server is Python-based, with Python on your PATH.

On Windows, confirm that Node.js is on your PATH by opening a new terminal after installation and running node --version. If the command is not found, add Node.js to PATH manually or reinstall with the “Add to PATH” option checked.

---

Command syntax

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

For HTTP servers the form is different — there is no -- separator:

claude mcp add --transport http [flags] <server-name> <url>

Key parts:

• <server-name> — a name you choose. Claude Code uses it for labeling tool calls in output and for commands like claude mcp remove.
• -- — separates Claude Code’s own flags from the command used to start the server. Everything after -- is passed verbatim to the subprocess.
• <command> [args...] — the program Claude Code runs when starting a stdio server.

Common flags:

Flag	Description
--transport	stdio (default) or http
--scope / -s	local (default), project, or user
--env / -e	Environment variable to inject into the server process (repeatable)
--header	HTTP header for HTTP/SSE transports (repeatable)

---

Transport types: stdio vs HTTP

stdio runs the server as a local subprocess. Claude Code launches the process, communicates with it over stdin/stdout, and keeps it alive for the session. This is the right choice for servers that need access to local resources — your filesystem, a local database socket, a browser. Most npm-based MCP packages use stdio.

HTTP connects to a server running at a URL. Claude Code makes HTTP requests rather than managing a subprocess. Use this for hosted services (Sentry, Linear, Notion, a team-deployed server) or for any server you want to share across machines.

There is also an older SSE transport that predates the HTTP standard. New deployments should prefer --transport http. Claude Code still accepts --transport sse for backward compatibility.

---

Adding a local stdio server

The Playwright MCP server is a good first server to try: it gives Claude a browser it can navigate and read, requires no API key, and runs through npx.

claude mcp add playwright -- npx -y @playwright/mcp@latest

The -y flag tells npx to install the package without prompting. Without it, the server process hangs waiting for input, which shows up as a connection timeout.

After running the command you will see:

Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest to local config

Check that it connected:

claude mcp list

The first check may show a timeout while npx downloads the package. Wait a moment and re-run. Once it shows ✓ Connected, start a session and use it:

Use playwright to open https://example.com and tell me the page title

---

Adding an HTTP server

HTTP servers are added with --transport http and a URL instead of a command:

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Some services require a static bearer token:

claude mcp add --transport http --header "Authorization: Bearer <token>" my-server https://api.example.com/mcp

Services that use OAuth (Sentry, Linear, Notion) do not take a token at add time. After running claude mcp add, start a Claude Code session and run /mcp, select the server, and choose Authenticate. Your browser opens to the service’s sign-in page. Once you approve the connection, the server status changes to connected.

---

Scope flags and config file locations

The --scope flag controls which config file Claude Code writes to, and which sessions the server becomes available in.

Scope	Flag	Config file	Available to
local	-s local (default)	~/.claude.json, under the current project entry	Only you, only this project
project	-s project	.mcp.json in the project root	Everyone who clones the project
user	-s user	~/.claude.json, top-level mcpServers key	Only you, all projects

On Windows, ~/.claude.json resolves to %USERPROFILE%\.claude.json — typically C:\Users\YourName\.claude.json. If you have set CLAUDE_CONFIG_DIR, Claude Code reads .claude.json from inside that directory.

Scope is fixed when you add a server. To change it, remove and re-add at the new scope:

# Remove the local entry, add at user scope
claude mcp remove playwright --scope local
claude mcp add --scope user playwright -- npx -y @playwright/mcp@latest

---

Team sharing with .mcp.json

Project-scoped servers write to .mcp.json in the project root. Commit this file to version control and every teammate who clones the repository gets the same server set.

The format:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "my-api-tools": {
      "type": "http",
      "url": "https://tools.internal.example.com/mcp"
    }
  }
}

For stdio servers, command and args are the program Claude Code runs. For HTTP servers, only url is required. If the server needs environment variables, add an env block:

{
  "mcpServers": {
    "my-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "your_key_here"
      }
    }
  }
}

The first time a teammate opens Claude Code in the project, they see a prompt to approve the project-scoped servers. This consent step prevents a cloned repository from launching processes without agreement. If they missed the prompt, /mcp lets them approve manually. To reset approvals for everyone, run claude mcp reset-project-choices.

---

Windows and PowerShell notes

claude mcp add works in PowerShell and Command Prompt the same as in bash. A few differences to keep in mind:

Environment variables in PowerShell: Set variables before the command on the same line:

$env:MCP_TIMEOUT = "60000"; claude

The MCP_TIMEOUT variable extends the server startup timeout (in milliseconds, default 30 seconds). Useful when npx is downloading a package for the first time.

Testing HTTP connectivity: PowerShell’s curl is an alias for Invoke-WebRequest, not the real curl binary. Use curl.exe to test server reachability:

curl.exe -I https://mcp.sentry.dev/mcp

npx path resolution: Most npm-based servers work without special configuration because Claude Code finds npx through your system PATH. If you see a connection error for a stdio server using npx, run the npx command directly in your terminal to confirm it executes. A command not found error means Node.js is not on your PATH. A command that starts and waits means the server itself works and the issue is elsewhere.

Config file location: On Windows, the user-scoped config is at %USERPROFILE%\.claude.json. If you set CLAUDE_CONFIG_DIR, the file moves to that directory. Claude Code does not read %APPDATA%\Claude\mcp.json — that path is for Claude Desktop, which is a separate application.

---

Connecting to Novita LLM API and Agent Sandbox

The claude mcp add command connects Claude Code to tool servers, but Claude Code itself still calls a backend LLM for reasoning. You can route those calls to Novita’s LLM API instead of the default Anthropic endpoint. Set two environment variables before starting a session:

ANTHROPIC_BASE_URL=https://api.novita.ai/anthropic \
ANTHROPIC_API_KEY=your_novita_api_key \
claude

This gives you access to cost-efficient models for coding tasks — useful when Claude Code is running long multi-step agents and per-token cost adds up.

For MCP tool execution that involves running code, the isolation question matters. A tool with file system access or network calls has a wide reach if it behaves unexpectedly. Novita Agent Sandbox provides isolated cloud environments where tool servers run independently of your local machine. The sandbox gets its own filesystem, network scope, and resource limits. The MCP server running inside it exposes tools through HTTP transport, and Claude Code connects to it remotely exactly as it would any other HTTP MCP server:

claude mcp add --transport http sandboxed-tools https://your-sandbox-instance.novita.ai/mcp

Sandboxes start in under 200ms and bill per second of active execution, so idle time between tool calls does not accumulate cost. For a full walkthrough of building a sandboxed MCP server, see Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library.

---

Managing registered servers

# List all servers and their connection status
claude mcp list

# Show the stored definition for one server
claude mcp get <server-name>

# Remove a server (defaults to local scope)
claude mcp remove <server-name>

# Remove from a specific scope
claude mcp remove <server-name> --scope user

# Reset project-level approval choices
claude mcp reset-project-choices

Each connected server loads its tool names and instructions into Claude’s context window at session start. Removing servers you are not actively using keeps that space available for the conversation.

---

Troubleshooting

Server added but shows “Failed to connect”

For stdio servers: run the command directly in your terminal to see the actual error output. For the Playwright server, run npx -y @playwright/mcp@latest and observe what happens. If it starts and waits for input, the server works and the issue is in how Claude Code is launching it — run claude mcp get playwright and verify the stored command matches.

For HTTP servers: confirm the URL is reachable. In bash run curl -I <url>, in PowerShell run curl.exe -I <url>. A 404 or 405 response usually means the URL is correct but the path is wrong for POST-based MCP endpoints.

“No MCP servers configured” inside a session

Local-scoped servers are tied to the directory where you ran claude mcp add. If you start Claude Code from a different directory, local servers from other projects are not active. Add the server again from the current project, or use --scope user to make it available everywhere.

Do not put server config at ~/.claude/mcp.json, ~/.claude.json nested under .claude/, or %APPDATA%\Claude\mcp.json. Claude Code reads only ~/.claude.json (for local and user scopes) and .mcp.json at the project root (for project scope).

Server connects but tools are never called

Claude selects tools based on their descriptions. Vague or incomplete descriptions lead to tools being overlooked. If you own the server, improve the description field in the tool definition. If you are connecting a third-party server, check its documentation to understand when its tools are intended to be invoked, and give Claude that context in your prompt.

Connection timeout on first run

npx may take longer than the 30-second default while downloading a package for the first time. Set a longer timeout with the MCP_TIMEOUT environment variable (value in milliseconds):

MCP_TIMEOUT=120000 claude

Server name already exists

If a server with that name is registered at the same scope, remove it first:

claude mcp remove <server-name>

If the name exists at multiple scopes, remove reports this. Pass --scope to target one copy.

---

FAQ

What does claude mcp add actually do?

It writes a server definition to a JSON configuration file. At session start, Claude Code reads that file, launches or connects to the server, fetches the tool list, and makes those tools available during the conversation.

What is the difference between local, project, and user scope?

local (default) registers the server only for you, only in the current project. project writes to .mcp.json in the project root, which you can commit so teammates share the same servers. user makes the server available to you across all projects.

Does claude mcp add work on Windows?

Yes. The command is identical in PowerShell, Command Prompt, and WSL. On Windows, the user-scope config lives at %USERPROFILE%\.claude.json. Use $env:MCP_TIMEOUT = "60000"; claude in PowerShell to set environment variables before starting a session.

Can I use the same MCP server in multiple projects?

Register it at --scope user and it is active in every project you open. Alternatively, include it in each project’s .mcp.json.

How do I pass API keys to an MCP server?

Use the --env flag at registration time:

claude mcp add my-tools python /path/to/server.py --env API_KEY=your_key

For .mcp.json, add an env block under the server entry. Do not embed credentials in the server command itself.

What is claude mcp serve?

claude mcp serve runs Claude Code as an MCP server, exposing its capabilities to another MCP host. This is for multi-agent setups where a different orchestrator needs to use Claude Code as a tool source, not for standard tool-use workflows.

---

Recommended Articles

• Claude MCP: How to Configure MCP Servers in Claude Code and Claude Desktop
• How to Build Your First MCP Server with Novita AI
• Claude Code CLI Documentation: Setup, Slash Commands, and LLM API Integration