How to Add an MCP Server to Claude Code (Step by Step)

To add MCP to Claude Code, run claude mcp add in your terminal. For a local (stdio) server use claude mcp add --transport stdio <name> -- <command>; for a remote (HTTP) server use claude mcp add --transport http <name> <url>. Choose a scope — local, project, or user — and Claude Code writes the server to its config so its tools are available in your next session.

Command syntax and scope behaviour verified 31 July 2026 against the Claude Code MCP documentation.

MCP servers — built on the open Model Context Protocol, the standard Anthropic introduced in November 2024 — are how you give Claude Code new tools and data: a database, a browser, an issue tracker, your docs. The good news is that adding one is a single command once you know the shape of it. This guide shows you exactly how to add MCP to Claude Code: the command, stdio versus HTTP servers, the three scopes, the .mcp.json file, and how to verify and manage what you've installed. Claude Code currently ships with the latest models like Claude Opus 5 and Claude Sonnet 5, and this walkthrough is reviewed regularly so the claude mcp add steps stay accurate — most take under 30 seconds to run. In our own setup the add command is rarely the hard part; picking the right scope is, and getting it wrong is exactly why a server you thought you installed seems to vanish the moment you switch projects.

How to add MCP to Claude Code: the command

Everything runs through claude mcp add <name> -- <command>. Two rules cover most failures: every option — --transport, --scope, --env, --header — goes before the server name, and -- separates that name from the launch command.

Everything runs through the claude mcp add command. The general form is:

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

Two rules save you most of the headaches. First, all the options — --transport, --scope, --env, --header — go before the server name. Second, the -- (double dash) separates the server name from the command and arguments that launch a stdio server. Get those two right and the command works for almost any server on the first try.

You don't have to touch a config file by hand — the command writes it for you — but it helps to know one exists, which we'll cover under scopes. The official Claude Code MCP quickstart lists every flag if you want the full reference.

stdio vs HTTP servers

stdio servers are local processes Claude Code launches and talks to over standard input/output, which is the common case. HTTP servers are hosted and reached by URL, with --header carrying any auth token. Pick the transport flag that matches.

There are two kinds of MCP server, and which flags you pass depends on which you have.

stdio (a local process). Most MCP servers run as a local command Claude Code launches and talks to over standard input/output. You add one like this:

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

Everything after -- is the command Claude Code runs to start the server.

HTTP (a remote service). Some servers are hosted and you connect over the network. Point Claude Code at the URL:

claude mcp add --transport http my-server https://your-server-url

For authenticated HTTP servers, pass a header with --header "Authorization: Bearer <token>". That's the whole surface area — once you know which transport your server uses, you register it with the matching flag.

One habit worth building from the start: after you add a server, open a fresh session and run /mcp to confirm it actually connected rather than assuming it did. In our own setup this is where most "it isn't working" moments resolve themselves — the server was written to a different scope than the project we were sitting in, or it failed to launch because the start command was missing a dependency, and the /mcp list surfaces both states immediately instead of leaving you to guess why a tool never appeared. It takes five seconds and saves the reinstall-everything spiral. Upstash's Context7, a third-party documentation server, is a typical example of that hosted pattern, and our Context7 Claude Code setup guide walks through the header and scope flags it needs. If you're on a free account and wondering how much of this is open to you, our guide to using MCP on the Claude free plan explains which routes work without a subscription.

Choose a scope: local, project, or user

Scope decides who sees a server, and it is fixed at install time. Local keeps it private to one project, project writes it to a committed .mcp.json for the whole team, and user registers it across all your own projects.

When you add MCP to Claude Code, the server is written to a configuration at one of three scopes, and picking the right one matters because a server's scope is fixed when you add it:

• Local is the default — private to you and active only in the folder you're in. Good for experiments.
• Project writes the server into a .mcp.json file at the project root. Commit that file and every teammate (and every machine) gets the same MCP setup automatically — the best choice for shared tooling.
• User registers the server once for all of your own projects — ideal for a personal tool you always want available.

Because scope is set at add time, changing it means removing the server and re-adding it at the new scope, so decide up front how widely you want to add MCP to Claude Code.

Where does Claude Code store your MCP config?

Local and user servers live in Claude Code's own settings outside the repository, which is why teammates never see them. Project servers live in a plain .mcp.json at the project root, readable and reviewable in a pull request.

You rarely need to edit it directly, but knowing where each scope lives makes debugging easier when you add MCP to Claude Code:

• Local and user servers are stored in Claude Code's own settings on your machine, outside the repo — which is why they don't show up for teammates.
• Project servers live in a plain .mcp.json file at the root of your project. Because it's just JSON in your repo, you can read it, diff it in a pull request, and review exactly what tools a project grants Claude Code before you approve them.

That last point is a quiet security win: since project-scoped servers are committed as readable config, your team can vet every server someone adds rather than trusting an opaque setup. When you clone a repo that has a .mcp.json, Claude Code asks before enabling its servers the first time.

Verify and manage your MCP servers

Three sibling commands cover the lifecycle: claude mcp list shows every server with a live connected or failed status, claude mcp get prints one server's full config for debugging, and claude mcp remove deletes it.

After you add MCP to Claude Code, confirm it's connected and manage it with the sibling commands:

claude mcp list          # all servers + live connection status
claude mcp get my-server # full config for one server
claude mcp remove my-server

claude mcp list shows each server with a connected/failed status — the fastest way to confirm your new server is live. If it shows failed, claude mcp get reveals the exact command and environment so you can spot the problem. Our guide to the claude mcp list command goes deeper on reading and managing that output. Inside a session, /mcp shows the same servers and their tools.

Example: adding a real server

A browser-control server makes the pattern concrete: register Playwright at project scope with one command, run claude mcp list to confirm it shows connected, and Claude Code can open pages and take screenshots inside your task.

Say you want to give Claude Code the ability to control a browser. You'd add the Playwright MCP server at project scope so your whole team gets it:

claude mcp add --transport stdio playwright --scope project -- npx -y @playwright/mcp

Run claude mcp list, confirm playwright shows connected, and Claude Code can now open pages and take screenshots as part of its work. That same pattern — pick the package, choose a scope, add MCP to Claude Code, verify — works for database servers, GitHub, your docs, and hundreds of others. If you'd rather install bundles of tools at once, the plugin marketplace packages MCP servers alongside commands and subagents, and our Blender MCP walkthrough shows a full real-world integration.

Troubleshooting

Four causes explain nearly every failed connection: options placed after the server name, a missing -- before the launch command, a launch binary that is not on your PATH, or a server installed at the wrong scope.

When you add MCP to Claude Code and it won't connect, the usual causes are quick to fix:

• Options after the name. --transport and --scope must come before the server name, or the command misreads them.
• Missing --. For stdio servers, forgetting the double dash means Claude Code doesn't know where the launch command starts.
• The command isn't installed. If the server runs via npx or a binary, make sure that tool exists on your PATH — Node.js for Claude Code covers getting npx working cleanly.
• Wrong scope expectations. If teammates don't see a server, you probably added it at local scope; re-add it with --scope project.

If the protocol itself still feels abstract, we have Claude MCP explained in plain English — hosts, clients, servers, and why any of it exists.