Guide · updated 2026-10-14 · 10 min read

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

To add an MCP server to Claude Code, run claude mcp add in your terminal. Use claude mcp add --transport http <name> <url> for a hosted server, or claude mcp add <name> -- <command> for a local one that runs on your machine. Then run claude mcp list (or /mcp inside a session) and check that it says ✔ Connected.

That covers most cases. The rest of this guide covers what actually trips people up: scopes, .mcp.json, auth, and what to do when the status is red. I checked everything here against Anthropic's MCP quickstart and MCP reference as of October 2026.

The two commands you need

# Hosted server (HTTP)
claude mcp add --transport http <name> <url>

# Local server (stdio), everything after -- is the command to run
claude mcp add <name> -- <command> [args...]

Run these in your shell, not inside a claude session. You can pick any name. Claude Code uses it to label the server's tools and to refer to the server in commands like claude mcp remove.

Add a hosted HTTP server

Anthropic runs a docs server that needs no sign-in, so it's a good first test.

1. Add it:

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

You should see a confirmation that it was added "to local config", plus a File modified: line showing which file it wrote.

2. Check it:

bash claude mcp list

3. Use it. Start claude and ask something like Use the claude-code-docs server to look up what MCP_TIMEOUT does. Claude normally picks tools on its own, so you don't need to name the server. Naming it on the first run proves the answer came through MCP and not from a web fetch. Approve the permission prompt the first time a tool is called.

About SSE: the docs mark the SSE transport as deprecated. If a service only offers an SSE endpoint, use the same --transport http command. Versions v2.1.265 and later try HTTP first and fall back to SSE. On older versions, pass --transport sse.

Add a local stdio server

A stdio server is a program Claude Code launches as a subprocess. Use one when the tool needs something on your machine, like a browser, your filesystem or a database socket. The quickstart uses Microsoft's Playwright server, which needs Node.js 18 or later:

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

Three details matter here:

• No --transport flag. stdio is the default.
• The -- separator. Everything after it is passed to the server unchanged. Without it, Claude Code tries to parse the server's flags (say, --port 8080) as its own options. This is the easiest mistake to make, and it doesn't always produce an error. The entry can save with a different command than the one you meant, so the server never starts.
• "Added" doesn't mean "works". It only means the entry was saved. The first claude mcp list can show ✘ Failed to connect while npx downloads the package. Wait and run it again.

If the server needs an API key, pass it with --env:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Note that --transport stdio sits between --env and the name. --env accepts multiple KEY=value pairs, so if the name comes right after it, the CLI reads the name as another pair and rejects it. Put any other option in between.

Servers that need sign-in or a token

OAuth (Sentry, Linear, Notion and similar): add the URL as normal, then sign in from inside a session.

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

claude mcp list will show ! Needs authentication, which is expected. To sign in:

1. Start claude and run /mcp.
2. Select the server and choose Authenticate.
3. Finish the sign-in in your browser. If the browser doesn't open, copy the URL from the terminal.

Static token: pass it as a header when you add the server. GitHub's remote server is the documented example:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

The reference notes that add doesn't check credentials. A placeholder token saves fine and then fails to connect, so check /mcp after adding.

Pick the right scope

Every server lives in one of three scopes, set with --scope:

How I use them:

• user for personal tools I want everywhere, like a docs server or a browser.
• project for anything the codebase depends on, like the team's issue tracker or a staging database server. It gets committed, so it's reviewed like code.
• local for experiments and anything with a personal token I don't want in the repo.

Two more things about scope. First, it's fixed when you add a server. To move one, remove it and add it again:

claude mcp remove claude-code-docs --scope local
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

Second, if the same name exists in more than one scope, Claude Code uses only the highest-priority definition. The order is local, then project, then user, then plugin servers, then claude.ai connectors, and fields are not combined between them. So an old local entry can quietly override the corrected project entry. claude mcp get <name> shows which scope holds the definition.

Writing .mcp.json by hand

For project scope I usually skip the CLI and write the file directly, since it's going into the repo anyway. Here's a .mcp.json with two HTTP servers and one stdio server:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

The rules that matter:

• Always set type on URL-based servers. Claude Code reads an entry with a url but no type as stdio and skips it with an error. streamable-http works as another name for http, so configs copied from server READMEs usually work.
• Keep secrets out with ${VAR}. Variables work in command, args, env, url and headers, and ${VAR:-default} gives a fallback value. If a variable isn't set and has no default, the config still loads. claude mcp list shows a warning, and the literal ${VAR} text gets used. When that's a token in a header, it can look like an auth failure.
• Restart after editing. Claude Code reads .mcp.json when a session starts.
• Expect an approval prompt. The first time Claude Code sees a project server, it asks before launching it, so a cloned repo can't run processes on your machine without your consent. If you rejected one by accident, run claude mcp reset-project-choices.

Verify with /mcp and claude mcp list

claude mcp list in the shell and /mcp inside a session show the same statuses. The ones you'll see:

You can also use /mcp to reconnect, sign in, browse a server's tools, and turn a server off without deleting its config.

Fixing servers that won't connect

Work through these in order. According to the quickstart's troubleshooting section, most failures fall into one of them.

1. "No MCP servers configured." Either you added the server at local scope in a different project, or you edited a file Claude Code doesn't read. Only ~/.claude.json and <project>/.mcp.json count. Add it again from the right directory or use --scope user.
2. Read the error detail. On v2.1.219 and later, claude mcp get <name> shows the HTTP status or error text for Failed to connect. Also check claude mcp list for warnings. It flags hidden spaces at the start or end of config values, which often happens when you paste a token.
3. stdio: run the command yourself. Paste the exact command (e.g. npx -y @playwright/mcp@latest) into a terminal. If it starts and waits for input, the server works and your config is the problem. Compare it with claude mcp get <name> and check for a missing --. If it errors, the message usually names what's missing, like Node.js or a browser.
4. HTTP: curl the URL. Run curl -I <url> (use curl.exe in PowerShell). - A 404 or 405 still means the host is reachable, since many MCP endpoints only accept POST. - A 401 or 403 means you need to authenticate. - No response means a bad URL or a network problem. - If /mcp says the endpoint wasn't found, the path is probably wrong. Remove the server and add it again with the right URL.
5. Timeouts on startup. The default startup timeout is 30 seconds, and a first npx run can take longer. Raise it in milliseconds: MCP_TIMEOUT=60000 claude.
6. Connected, but no tools. This usually means a missing environment variable such as an API key. Add it with --env or in the server's env field.
7. "Already exists." A server with that name already exists at the same scope. Remove it first, passing --scope if it exists in several scopes.

Don't add everything

Each connected server uses some context, because tool names and server instructions load in every session. Tool search is the default on most setups and holds back full tool definitions until Claude needs them. That helps a lot, but it isn't free and it isn't available on every deployment. My rule: if I haven't used a server in two weeks, I remove it. For the rest of my day-to-day setup habits, see Claude Code Best Practices.

Also ask whether you need a server at all. If you just want a repeatable workflow or a set of instructions, a skill is often lighter. See Claude Code Skills: How to Build and Use Them. And if Claude keeps ignoring a server you do need, one line in your project instructions about when to use it usually fixes that (how to write a CLAUDE.md that Claude follows).

Bottom line

Use claude mcp add --transport http <name> <url> for hosted servers and claude mcp add <name> -- <command> for local ones. Always confirm with claude mcp list or /mcp, because "Added" only means the config was saved. Put personal tools at user scope, team tools at project scope (a committed .mcp.json with ${VAR} for secrets), and experiments at local. When a status is red, read claude mcp get, then run the command or curl the URL yourself. In my experience that finds the cause most of the time.

If this was useful, you're welcome to subscribe to Agent Shipped for guides like this one: free, twice a week, a 4-minute read.

Notes: - Sources: Every command, file path, status and version number comes from Anthropic's MCP quickstart and reference docs, retrieved October 6, 2026. My fetch tool doesn't return citable sentence indices, so sources are linked inline instead. - Version-specific details: These include v2.1.219 for error detail on Failed to connect and v2.1.265 for falling back to SSE. Check them again if you update the guide later. - Not included: I left out Windows-specific npx wrapper advice because the current docs don't mention it and I couldn't confirm it. - Lines that need your approval: The "two weeks" removal rule and "In my experience" are written as your first-person opinions, so you may want to keep or change them. - Length: The body is about 1,870 words.

FAQ

Where does Claude Code store MCP server configuration?

Local and user scoped servers live in ~/.claude.json. Local ones sit under the entry for the current project, and user ones sit under the top-level mcpServers key. Project scoped servers live in .mcp.json at the project root, and Claude Code doesn't read paths like ~/.claude/mcp.json, so editing those does nothing.

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

Local is the default and is private to you in the current project. Project writes to .mcp.json, so everyone who clones the repo gets the server after approving it. User is private to you but active in every project.

Why does my MCP server say "Failed to connect"?

Either the server process didn't start, the URL didn't respond or the server rejected your token. Run claude mcp get <name> to see the error detail. Then run the stdio command yourself in a terminal, or curl the HTTP URL, to find the underlying problem.

Can I reuse the MCP servers I set up in Claude Desktop?

Yes. On macOS or WSL you can run claude mcp add-from-claude-desktop to copy servers from Claude Desktop's config into the CLI. Claude Desktop and Claude Code are separate apps, so otherwise nothing is shared automatically.

Do MCP servers use up Claude Code's context window?

Yes, some. With tool search, which is the default on most setups, only tool names and server instructions load at session start, and full tool definitions load when needed. Removing servers you no longer use still frees that space.