# 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.

The whole loop in one screen: add the server, confirm it connects, then let Claude use it. Illustrative session.

If you have not met the protocol yet, read [MCP fundamentals](/guides/mcp-fundamentals)
first. It explains what a server 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 scope ties the server to the
  project you add it from.
- For local servers that run through `npx`, [Node.js](https://nodejs.org)
  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:

| Command | What it does |
| --- | --- |
| `claude mcp add` | Registers a server with Claude Code |
| `claude mcp list` | Shows every server and its connection status |
| `claude mcp get ` | Shows one server's full config and scope |
| `/mcp` (inside a session) | Checks status, signs in, reconnects |

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:

```bash
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.The 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:

```bash
claude mcp list
```

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

| Status | Meaning |
| --- | --- |
| `✓ Connected` | Ready to use. This is what `claude-code-docs` should show |
| `! Needs authentication` | Reachable, but needs a browser sign-in or a token |
| `✗ Failed to connect` | The server did not respond |
| `✗ Connection error` | The connection attempt threw an error |
| `⏸ Pending approval` | A project-scoped server you have not approved yet |

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:

```bash
claude
```

Use the claude-code-docs server to look up what MCP_TIMEOUT does.

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 stdio 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](/guides/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`:

```bash
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.Easy 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 ` 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:

```bash
claude mcp list
```

Use playwright to open https://example.com and tell me the page title.

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:

```bash
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:

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

For hosted services that use OAuth, 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 | Loads in | Shared with team | Stored in |
| --- | --- | --- | --- |
| `local` (default) | This project only | No | `~/.claude.json` |
| `project` | This project only | Yes, via version control | `.mcp.json` in project root |
| `user` | All your projects | No | `~/.claude.json` |

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:

```bash
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:

```bash
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:

```json
{
  "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:

```json
{
  "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:

```bash
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:

```bash
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](/guides/fix-an-mcp-server-that-wont-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 `. 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 ` 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](https://claude.ai/directory)
for reviewed servers, share your set with a committed `.mcp.json`, and read
[MCP fundamentals](/guides/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](/guides/mcp-security-basics).