Claude Code MCP: The Complete Setup Guide (2026)

MCP (Model Context Protocol) is how Claude Code talks to the world outside your repo: databases, browsers, issue trackers, internal APIs, registries. Setting up Claude Code MCP servers takes one command — claude mcp add <name> -- <command> registers a server, and Claude Code connects to it at the start of your next session, exposing the server's tools alongside the built-in ones.

That one command hides real decisions, though: which scope the server should live in, whether it should run locally over stdio or remotely over HTTP, how credentials get handled, and how to keep ten servers' worth of tool definitions from eating your context window. This guide walks through the full workflow — adding servers, the .mcp.json format, authentication, debugging, and sharing your Claude MCP config with a team.

How MCP fits into Claude Code

MCP is an open protocol that standardizes how AI applications connect to external tools and data sources. Claude Code is an MCP client: every server you register either runs as a child process on your machine or sits behind an HTTP endpoint, and it advertises a list of tools to Claude Code when the session starts.

Those tools show up namespaced as mcp__<server>__<tool> — so a GitHub server's issue search becomes mcp__github__search_issues. When Claude decides a task needs one of them (query this database, fetch that ticket), it calls the tool through the protocol and gets structured results back, exactly like it uses its built-in file and shell tools.

There are three transports you'll encounter:

• stdio — Claude Code spawns the server as a local process and speaks JSON-RPC over stdin/stdout. Most open-source servers work this way.
• HTTP — the server is hosted remotely; Claude Code talks to a URL. This is where OAuth-protected servers live.
• SSE — an older remote transport you'll still see in some docs. Prefer HTTP for new setups.

If the protocol itself is new to you, start with our explainer on what an MCP server actually is, then come back here for the Claude Code specifics.

Adding MCP servers to Claude Code

Here's the end-to-end flow to add an MCP server to Claude Code, from install to verification.

1. Add a server with claude mcp add

Everything after -- is the command Claude Code will run to start the server:

# Add MCP server to Claude Code over stdio
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost:5432/dev

# Pass environment variables (API keys, tokens) with -e
claude mcp add github -e GITHUB_TOKEN=ghp_yourtoken -- npx -y @modelcontextprotocol/server-github

For remote servers, pass a URL and a transport instead of a command:

claude mcp add --transport http localskills https://localskills.sh/mcp

If you already have a server definition as JSON — from a README, or copied from another tool — claude mcp add-json takes it directly:

claude mcp add-json postgres '{"command":"npx","args":["-y","@modelcontextprotocol/server-postgres","postgresql://localhost:5432/dev"]}'

2. Pick a scope

By default the server is registered with local scope: it exists only for you, only in the current project. Use -s / --scope to change that:

# Available to everyone who clones this repo (written to .mcp.json)
claude mcp add playwright -s project -- npx -y @playwright/mcp

# Available to you in every project on this machine
claude mcp add localskills -s user --transport http https://localskills.sh/mcp

Scopes are the part most people get wrong, so the next section covers them properly.

3. Verify the connection

claude mcp list shows every registered server and whether Claude Code can actually reach it:

claude mcp list
# postgres: npx -y @modelcontextprotocol/server-postgres ... - ✓ Connected
# github: npx -y @modelcontextprotocol/server-github - ✓ Connected

Use claude mcp get <name> to inspect a single server's config, and claude mcp remove <name> to delete one. Inside a session, the /mcp slash command shows live status for each server plus the tools it exposes.

Claude Code MCP scopes and the .mcp.json file

Every server lives in exactly one of three scopes, and the scope determines where the config is stored and who else gets it:

If the same server name exists in multiple scopes, local wins over project, and project wins over user.

The file worth knowing well is .mcp.json — the project-scoped MCP JSON config that gets checked into version control. It uses the same mcpServers shape you'll see across MCP clients:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/dev"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Two things make this file team-safe. First, Claude Code expands environment variables in it — ${VAR} reads from the developer's environment, and ${VAR:-default} supplies a fallback — so secrets never need to be committed. Second, Claude Code prompts each developer to approve a project's .mcp.json servers before running them the first time, so cloning a repo can't silently execute arbitrary commands on your machine. If you need to re-trigger those prompts, run claude mcp reset-project-choices.

You can edit .mcp.json by hand instead of using claude mcp add -s project; the CLI and the file are two views of the same config.

Local vs remote servers and authentication

Local (stdio) servers run as processes on your machine. They're the right choice when the server needs local access — your filesystem, a database on localhost, a browser it drives directly. Credentials are your problem: pass them as environment variables via -e or the env block, and prefer ${VAR} expansion over hardcoding tokens in config files.

Remote (HTTP) servers are hosted by whoever provides them. There's nothing to install or keep updated, and authentication is typically OAuth: after adding the server, run /mcp inside a session, select the server, and choose Authenticate. Claude Code opens a browser for the OAuth flow and manages the tokens from there. For simpler API-key setups, claude mcp add accepts --header flags:

claude mcp add --transport http internal-api https://api.example.com/mcp --header "Authorization: Bearer ${API_TOKEN}"

OAuth matters for remote servers because it gives you scoped, revocable access instead of a long-lived key sitting in a dotfile. The localskills.sh MCP server works this way: agents can search the registry and install skills over MCP, with OAuth and scoped access controlling what each connection is allowed to do.

A reasonable default: use remote HTTP servers for hosted services that offer them, and stdio for anything touching your local environment.

Debugging Claude Code MCP servers

When a server misbehaves, work through this sequence:

1. claude mcp list — the fastest signal. A server marked as failed never completed the MCP handshake; a missing server usually means a scope mix-up (registered as local in a different project, for example).
2. /mcp inside a session — shows per-server status, the authentication state for remote servers, and the exact tool list each server advertises. If a tool you expected isn't listed, the server connected but didn't expose it.
3. claude --debug — starts Claude Code with verbose logging, including MCP connection attempts and errors. This is where you'll see the actual stderr output from a crashing stdio server.

The most common failure causes, roughly in order:

• A missing environment variable. The server starts, then errors on its first real call. Check the env block and confirm the variable exists in the shell you launched claude from.
• stdout pollution. stdio servers must speak only JSON-RPC on stdout. A server (or a wrapper script) that prints a banner or debug line to stdout breaks the handshake. Logs belong on stderr.
• The command isn't on PATH. npx resolves against your shell environment; version managers like nvm can make a server work in one terminal and fail in another.
• Slow startup. npx -y downloads the package on first run, which can blow past the connection timeout. Set MCP_TIMEOUT=10000 (milliseconds) in your environment if a server needs more time to boot.

If the server fails even in isolation, take Claude Code out of the loop and test it with the MCP Inspector — our guide to debugging MCP servers with the Inspector covers that workflow.

Managing context cost as your server list grows

Here's the part that bites later: every connected server's tool definitions — names, descriptions, full input schemas — are loaded into context at session start, before you've typed anything. Five servers exposing fifteen verbose tools each can quietly consume a meaningful slice of your context window, and that cost recurs in every session whether or not you use the tools.

Run /context inside a session to see the breakdown, including how much MCP tools contribute. Then trim:

• Remove servers you don't use. claude mcp remove is free; re-adding later is one command.
• Scope narrowly. A database server for one project belongs in that project's scope, not user scope. User-scoped servers pay their context tax in every repo you open.
• Prefer servers with fewer, better-designed tools. A server exposing 40 thin wrappers around every API endpoint costs far more than one exposing 5 task-shaped tools.
• Cap runaway tool output. The MAX_MCP_OUTPUT_TOKENS environment variable limits how much a single tool result can inject into context.

We've written a deeper analysis of what too many MCP tools does to your token budget, including how to measure the overhead per server.

Team setup: sharing MCP config in version control

For a team, the goal is that git clone plus one approval prompt yields a fully wired setup. Project scope gets you there:

1. Add each shared server with -s project (or edit .mcp.json directly) and commit the file.
2. Reference secrets with ${VAR} expansion and document the required variables in your README — never commit tokens.
3. Each teammate approves the servers on first run; Claude Code remembers the choice per project.

This works well until you have many repos and the config starts drifting — one repo pins a server version, another doesn't; someone fixes an env var name in two places out of nine. Our post on sharing MCP servers across a team covers strategies for keeping a fleet of .mcp.json files consistent.

MCP config also rarely travels alone. The same teams that share servers usually want to share prompts, conventions, and skills across Claude Code, Cursor, and Windsurf — that's the problem localskills.sh solves: publish a skill once, and the CLI writes the tool-native format for each editor, including .claude/skills/ for Claude Code.

FAQ: common Claude Code MCP questions

Where is the Claude Code MCP config stored?

Local- and user-scoped servers live in ~/.claude.json (local scope is stored under the specific project's entry). Project-scoped servers live in .mcp.json at the repo root, which is designed to be committed to version control.

Why isn't my MCP server showing up in Claude Code?

Three usual suspects: the server is registered in a different scope or project (check claude mcp list from the repo in question), the connection failed at startup (run claude --debug to see the error), or it's a project-scoped server whose approval prompt was declined (run claude mcp reset-project-choices and restart).

Can I use the same MCP servers in Claude Code and Claude Desktop?

Yes — it's the same protocol, and the JSON server definitions are portable between clients. Claude Code can even import your existing Claude Desktop servers directly with claude mcp add-from-claude-desktop.

How many MCP servers should I connect?

As few as the project actually needs. Since every connected server adds its tool schemas to each session's context, the practical ceiling is lower than the technical one. Audit with /context, keep always-on servers to a handful, and add specialized ones at project scope only where they earn their cost.

What's the difference between MCP servers and Claude Code skills?

MCP servers give Claude capabilities — new tools it can call. Skills and rules give it knowledge and conventions — how your team wants those capabilities used. They complement each other: MCP extends what Claude Code can do, and skills shape how it does it.

---

Once your MCP setup is dialed in, the next bottleneck is sharing the conventions around it. Sign up for localskills.sh to publish your team's skills and rules once and install them across Claude Code, Cursor, Windsurf, and more.

npm install -g @localskills/cli
localskills login
localskills install your-org/your-skill --target claude cursor