Install your first MCP server in Claude Code

To add an MCP server to Claude Code, run claude mcp add in your terminal with the server's name and how to reach it, confirm it shows ✓ Connected in claude mcp list, then start a session and ask Claude to use it. This guide walks the whole loop end to end, with a real first server you can connect right now.

If you have not met the protocol yet, read MCP fundamentals first. It explains what a serverModel Context Protocol: an open standard from Anthropic that lets AI apps connect to tools and data through one common interface. is and how a tool call flows. This guide is the hands-on follow-up.

What you need first

Three things, all of which you set up once:

• Claude Code installed and authenticated. If claude --version prints a version, you are ready.
• A terminal open in a project directory. Any folder works, including an empty one. The directory matters because the default scopeWhere the server config is stored and which projects it loads in. ties the server to the project you add it from.
• For local servers that run through npx, Node.js version 18 or later.

The three commands you will use

Everything in this guide is built from three CLI commands plus one in-session panel:

Run the claude mcp commands in your shell, not inside a claude conversation. You are configuring the server before you start talking to Claude.

Step 1 · Add the server

Start with a hosted server that needs no account, so the first run is clean: the Claude Code documentation server. Run this in your terminal:

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

Read the parts left to right:

• claude mcp add registers a server.
• --transport http says the server lives at a URL rather than running as a local process.
• claude-code-docs is a name you pick. Claude Code uses it to label the server's tools in output and to refer to the server in later commands.
• The URL is where the server is hosted.

The command prints a confirmation like Added HTTP MCP server claude-code-docs ... to local config. The phrase local config is the key detail: the server is registered to you, in this project only. Open Claude Code in a different folder and this server is not there. You change that with scope, covered below.Common gotchaThe most common first-time surprise: you add a server, cd to another project, and it has vanished, since local is the default scope and ties the server to one folder.If you want a server in every project, add it with --scope user.

Step 2 · Confirm it connected

Adding a server writes its config. It does not prove the server answers. Check that next:

claude mcp list

Each server prints with a status indicator. Match yours against this table:

For a local server that installs through npx, the first list can show ✗ Failed to connect while the package downloads. Wait a moment and run it again.

Step 3 · Use it in a session

Now start Claude Code and ask it to use the server by name:

claude

The first time Claude calls a new server, it asks permission to use the tool. Approve it. In Claude's output, the tool call is labelled with the server name, which is how you confirm the answer came from the server and not from Claude's own knowledge.

You do not usually name the server in your prompt. Claude picks relevant tools on its own. Naming it here forces the demonstration through the new server so you can see it work.

How the pieces fit together

The flow is always the same three moves, whatever the server:

The status check sits in the middle for a reason. A registered server is not the same as a connected one, and catching a bad connection here saves you from debugging it mid-conversation.

How do I add a local MCP server?

A local stdioStandard input/output: the host launches the server as a child process and talks to it over plain text streams, no network. server is a program Claude Code starts on your machine rather than a service it reaches over a URL. Reach for one when the tool needs local access, like a browser, your filesystem, or a database socket. For the full trade-offs, see local vs remote MCP servers.

The Playwright server is a good first local server: it gives Claude a browser to drive and needs no account. It runs through npx:

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

Two parts differ from the hosted example:

• There is no --transport flag, because local servers use the default stdio transport.
• Everything after the -- separator is the command Claude Code runs to start the server.

That -- separator matters. It splits Claude's own options, like --env and --scope, from the command and arguments that belong to the server. Without it, Claude Code tries to read the server's flags as its own and the add fails. So claude mcp add myserver -- npx server runs npx server, untouched.Common gotchaEasy to drop the -- and write claude mcp add playwright npx -y @playwright/mcp@latest, which silently registers a server whose command is the bare word npx with no args, so it adds fine but shows ✗ Failed to connect later.Always put -- right before the launch command, and if a stdio server fails, run claude mcp get <name> and check the stored command is the full npx -y ... line, not a stray fragment.

Check the connection the same way, then give Claude a task that needs the browser:

claude mcp list

A browser window opens so you can watch it work, and the tool calls in Claude's output carry the playwright label.

How do I pass API keys to an MCP server?

Servers often need a key. For a local server, pass environment variables with --env, which accepts several KEY=value pairs:

claude mcp add --env API_KEY=your-key myserver -- npx -y some-mcp-server

For a hosted server that takes a static token instead of a browser sign-in, pass it as a header:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

For hosted services that use OAuthA standard that lets an app get limited access to your account through a browser sign-in, without you handing over a password., the sign-in happens after you add the server. The status reads ! Needs authentication. Open a session, run /mcp, select the server, choose Authenticate, and approve the connection in the browser tab that opens. The status flips to connected.

What is MCP server scope?

Scope decides which projects a server loads in and whether your team gets it. Set it with --scope when you add the server:

Scope is fixed when you add a server, so to change it you remove the entry and re-add it. To make the docs server available everywhere, private to you:

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

To share it with your team, add it at project scope and commit the file it writes:

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

Configuration as code: .mcp.json

Project scope writes to a file named .mcp.json in your project root. You can also write that file by hand, which makes your servers part of the repository. Every teammate who clones the repo gets the same set. The file uses one shape for every server type:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

The fields differ by type. HTTP servers carry a url. Stdio servers carry a command and its args. You can reference environment variables with ${VAR} or ${VAR:-default} so machine-specific paths and keys stay out of the committed file:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Claude Code reads .mcp.json at session start, so restart the session after you edit it. The first time it sees a project-scoped server, it prompts you to approve. That prompt is a safety gate: a repository you clone cannot launch processes on your machine without your consent. Approve it, or run /mcp to approve later.

How do I remove an MCP server?

Each connected server takes a slice of Claude's context window, because its tool names and instructions load into every session. Remove servers you no longer use:

claude mcp remove claude-code-docs

If the same name exists at more than one scope, remove reports it. Pass --scope to choose which copy to delete:

claude mcp remove claude-code-docs --scope local

Why won't my MCP server connect?

Most first-time failures fall into a short list, and fixing an MCP server that won't connect goes deeper on each. Check status with claude mcp list or /mcp, then match the symptom:

• No MCP servers configured. You added the server from a different folder. Local servers are tied to the project you added them in. Re-add from the current folder, or use --scope user so it is not tied to a project.
• ✗ Failed to connect on a hosted server. Confirm the URL answers from your machine with curl -I <url>. A 404 or 405 still means the server is up, since many endpoints answer only POST. A 401 or 403 means you need to authenticate.
• ✗ Failed to connect on a local server. Run the configured command directly in your terminal. If it starts and waits, the server works and the problem is the config. A common cause is a missing -- separator. Run claude mcp get <name> and check the command shown matches what you intended.
• Timed out at startup. A local server's first npx download can exceed the 30-second default. Raise it with the MCP_TIMEOUT environment variable, in milliseconds: MCP_TIMEOUT=60000 claude.
• Connected but no tools appear. Run /mcp, select the server, and look at its tool list. An empty list usually means a missing key. Add it with --env or in the server's .mcp.json entry.
• Edits to .mcp.json do nothing. Claude Code reads the file at session start. Restart the session. If you once rejected the approval prompt, run claude mcp reset-project-choices and restart.

Where to go next

You now have the full loop: add a server, confirm it connects, and let Claude call its tools. From here, browse the Anthropic Directory for reviewed servers, share your set with a committed .mcp.json, and read MCP fundamentals again with working tools in front of you. One safety note carries through all of it: only connect servers you trust, since a server that pulls in outside content can expose you to prompt injection. For what to allow and what to block, read MCP security basics.