How to Add MCP Servers to Claude Code (Complete Guide) Adding an MCP server to Claude Code usually takes one command and thirty seconds. But most people don't get tripped up on the command itself — they get tripped up on transport type, scope, and authentication, the three details that decide whether a server actually works once it's registered.

This is approachable for any developer who's comfortable in a terminal. Teams rolling out a dozen servers across GitHub, databases, and internal APIs need something more structured.

When configuration is off, the failures are quiet: a server that never connects, a token sitting in plain text inside a shared config file, or MCP tools that simply don't show up when you ask Claude Code to use them. This guide walks through the complete process — adding, verifying, and troubleshooting MCP servers in Claude Code — plus how to manage them safely as your setup grows past a handful of tools.

Key Takeaways

  • MCP servers turn Claude Code into an execution engine that reaches GitHub, databases, browsers, and internal APIs
  • Three CLI methods handle registration: claude mcp add, claude mcp add-json, and --transport for HTTP or SSE
  • Every server gets a scope (local, project, or user) that controls who can see and use it
  • Most failures trace back to auth tokens, JSON formatting, or scope mismatches, not the MCP protocol
  • Team rollouts need centralized governance (auth, access control, audit logs) before scaling past a few servers

Understanding MCP Servers and What You Need Before Adding One

MCP (Model Context Protocol) gives Claude Code a structured way to connect to external tools and data sources instead of relying only on its training data. Servers come in two flavors: local, which run on your machine via npx, Docker, or a binary and communicate over stdio, and remote, which are hosted elsewhere and connected over HTTP or SSE.

Before you add anything, make sure you have:

  • An up-to-date Claude Code CLI — run claude --version to check, and claude doctor if something seems off
  • Node.js/npx or Docker, depending on how the target server ships
  • The specific credentials that server requires: a GitHub personal access token, database credentials, or an API key

A few non-negotiables before you proceed:

  • Never hardcode tokens directly into commands or into files that get committed to version control
  • Confirm you're in the correct project directory before adding a server with local scope
  • Skip servers you haven't vetted for trust or active maintenance, since MCP is an open standard and quality varies a lot by maintainer

How to Add MCP Servers to Claude Code (Step-by-Step)

All three methods below register a server the same way under the hood. They just differ in syntax and when you'd reach for each one.

Step 1: Choose Your Scope

Every server you add lives in one of three scopes:

Scope Flag Visibility Storage
Local (default) --scope local Only you, current project Project entry in ~/.claude.json
Project --scope project Anyone using the repo .mcp.json in project root
User --scope user All your projects Top-level entry in ~/.claude.json

If a name exists in more than one scope, local wins over project, which wins over user. Project-scoped servers also require a one-time approval before Claude Code will use them.

Step 2: Pick the Right Add Command for Your Server Type

For a simple local server run via npx or a binary, use claude mcp add:

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

Everything after -- is passed straight to the server as its launch command.

For servers needing custom headers or a remote HTTP/SSE connection, claude mcp add-json gives you more control:

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

Notice the header references an environment variable rather than a raw token. That's the pattern to copy every time.

There's also a direct --transport flag, which Anthropic's Claude Code documentation still supports for both HTTP and SSE:

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

SSE is marked deprecated in favor of HTTP, but the flag itself hasn't been removed. It's worth keeping in your back pocket for shells where add-json's quoting gets messy. This same command style also works for connecting to a multi-provider MCP gateway like FastRouter, which exposes 100+ models through one registered endpoint instead of one server per provider.

Step 3: Handle Docker-Based Servers (If Applicable)

Some servers ship as Docker images instead of npm packages. In that case, the docker run invocation becomes the command you pass to claude mcp add, following the same pattern as any other stdio server. Two auth patterns show up here: token-based, where you pass the credential as an environment variable inside the Docker command, and OAuth-based, where the server opens a browser login window the first time you connect and you authenticate through that flow instead of a static token.

Always verify the container starts correctly on its own with docker run before wiring it into Claude Code. It's a lot easier to debug a Docker problem outside Claude Code than inside it.

Step 4: Restart and Confirm Registration

After adding a server, restart Claude Code or reload your session. New servers and their tools don't show up mid-session automatically in most cases. The exception is .mcp.json edits made manually, where /mcp → Reconnect can pick up changes without a full restart.

4-step process for adding MCP servers to Claude Code

Verifying Your MCP Server Setup

Don't assume a server works just because the add command succeeded. Run these three checks, in order:

  1. claude mcp list shows every configured server and its status: Connected, Needs authentication, Failed to connect, or Pending approval
  2. claude mcp get <name> shows the full config for one server, including scope, URL, and any error detail
  3. /mcp inside an active session shows live connection status and, critically, the tool count for that server

If all three look healthy, test it for real. Give Claude Code a prompt that requires the new tool — something like "list open issues in this repo" for a GitHub server.

According to Anthropic's mcp-quickstart guide, Claude Code should prompt you for permission before it calls the tool for the first time. If it doesn't ask, and it doesn't return the expected result, the connection status alone isn't telling you the whole story.

Common Problems When Adding MCP Servers (and Fixes)

Nearly every setup failure comes down to authentication, JSON formatting, or scope and session issues — rarely the MCP protocol itself.

Issue 1: Server Shows as Disconnected or Unauthorized

Problem: The server appears in claude mcp list but won't connect, or throws an auth error.

Likely cause: An expired or incorrectly scoped token, or a malformed Authorization header in the JSON config.

Fix: Regenerate the token with the correct scopes, then remove and re-add:

claude mcp remove weather-api
claude mcp add-json weather-api '{"type":"http","url":"...","headers":{"Authorization":"Bearer $NEW_TOKEN"}}'

Issue 2: "Invalid Input" Error When Using add-json

Problem: add-json fails outright, especially on Windows or in PowerShell.

Likely cause: Shell-specific quote escaping mangles the JSON payload before it reaches Claude Code.

Fix: Switch to the --transport flag format instead, or carefully escape quotes for PowerShell before rerunning the command. If you're bouncing between shells often, the --transport flag is less fragile.

Issue 3: Server Added But Tools Never Get Used

Problem: The server is listed as connected, but Claude Code never actually calls its tools during a session.

Likely cause: Wrong scope (added under a different project), the session wasn't restarted, or a Docker container isn't actually running.

Fix:

  • Confirm your working directory matches the scope you intended
  • Restart Claude Code and re-check /mcp
  • Run docker ps to confirm the container is live, if applicable

Three common MCP server connection issues and their fixes

Most of these issues trace back to manual token and config handling. If you'd rather skip that overhead, FastRouter's MCP gateway pre-configures authentication and formatting for Claude Code, so servers connect without hand-editing JSON or managing tokens directly.

Best Practices for Managing MCP Servers as You Scale

Start minimal. Add only the servers tied to your actual daily workflow (GitHub, filesystem, maybe one database) before reaching for niche integrations you'll use twice a year.

Keep secrets out of shared files:

  • Store tokens in .env, never in .mcp.json or a command string
  • Add .env and .mcp.json to .gitignore
  • Reference environment variables in headers, not hardcoded credentials

Scope deliberately. Use project scope only for configs meant to be shared and reviewed by teammates. Reserve user scope for personal productivity tools: a project-scoped server with your personal token in it is how credentials end up leaking team-wide.

The real friction shows up once a team moves from a handful of personal servers to dozens spread across GitHub, Slack, databases, and internal APIs. Managing auth and access per developer, per server, by hand, stops being sustainable fast. This is the gap a dedicated MCP gateway is built to close.

FastRouter's MCP Gateway, for example, works as a registry that lets agent teams discover, consume, and govern MCP servers from one place instead of juggling ad-hoc tokens across a dozen config files, with routing, access controls, and observability built in from day one. It's included across FastRouter's platform tiers, and free credits are available if you want to test it against your own servers before rolling it out to a full team.

FastRouter MCP Gateway dashboard showing server registry and access controls

Whatever route you take, document each server you add: name, purpose, owner. Rotating credentials and auditing access only stays manageable if you know who owns what.

Frequently Asked Questions

What is the exact command to add an MCP server to Claude Code?

Use claude mcp add <name> -- <command> for local/stdio servers, or claude mcp add-json <name> '<json config>' for remote HTTP/SSE servers. The --transport http or --transport sse flag works as a direct alternative on both current and older CLI versions.

How do I remove an MCP server from Claude Code?

Run claude mcp remove <name>. This is usually the first step when troubleshooting a broken configuration: clear it out, then re-add it with corrected settings.

What's the difference between local, project, and user scope?

Local scope is private to you in the current project. Project scope is shared with your team through a .mcp.json file. User scope makes the server available across every project you work on.

Can I add a remote MCP server without using Docker?

Yes. Remote servers connected over HTTP or SSE, such as FastRouter's MCP gateway, don't need Docker at all. Docker only comes into play for servers packaged and run as local containers.

Do I need to restart Claude Code after adding a new MCP server?

Generally yes — restart or reload the session so the new server and its tools become visible. Manual edits to .mcp.json can sometimes be picked up with /mcp → Reconnect instead.

Is every MCP server compatible with Claude Code?

Claude Code supports any server built to the open MCP standard, but Anthropic's documentation doesn't guarantee every implementation will work smoothly. Check a server's docs and update history before adding it to anything you depend on.