Skip to content

code-mcp-quickstart.md

Latest commit

 

History

History
385 lines (264 loc) · 22 KB

code-mcp-quickstart.md

File metadata and controls

385 lines (264 loc) · 22 KB
title Connect to MCP servers
source https://code.claude.com/docs/en/mcp-quickstart
category code
generated true

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.

Connect to MCP servers

Add an MCP server to Claude Code, verify the connection, and find the configuration on disk.

The Model Context Protocol (MCP) lets Claude Code use tools beyond its built-in set, such as searching an issue tracker, querying a database, or controlling a web browser. These tools come from MCP servers, which run on your machine or as hosted services.

This guide walks you through connecting one MCP server end to end with the Claude Code CLI. By the end, you'll have a server connected and responding, know where its configuration lives on disk, and know how to fix the most common connection errors.

You can also add MCP servers from other surfaces, including the desktop app, VS Code, and the web. See [Connect from other surfaces](#connect-from-other-surfaces).

For every way to connect and configure MCP servers in Claude Code, see the MCP reference.

Before you begin

Make sure you have:

  • Claude Code installed and authenticated
  • A terminal open in a project directory. Any directory works, including an empty one.

Add and verify a server

The example below connects to the Claude Code documentation MCP server, a hosted server with full-text search over the Claude Code docs. It doesn't require authentication or any special configuration, so it works well as a first server to test the setup flow with.

The steps are the same for any server: add it, check the connection status, then use it in a session, with an optional cleanup step at the end. Some servers add a step, like a browser sign-in, shown in Additional MCP server examples. For more servers to connect, browse the Anthropic Directory.

Register the server with Claude Code. Run this in your terminal, not inside a `claude` session: you're configuring the server before starting a conversation. 
```bash theme={null}
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
```

The parts of the command:

* `claude mcp add`: registers a server with Claude Code.
* `--transport http`: the server is hosted at a URL rather than run as a local process.
* `claude-code-docs`: a name you make up. Calling the same server `docs` would work identically. Claude Code uses whatever name you pick to label the server's tools in Claude's output and to refer to the server in commands like `claude mcp remove`.
* `https://code.claude.com/docs/mcp`: the URL where the server is hosted.

The command prints a confirmation like `Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config`. The `local config` part means the server is registered to you, in this project: if you start Claude Code in a different project, this server isn't active there. To register a server once for all your projects, add it at user scope, covered in [Change server scope](#change-server-scope).
Confirm the server appears in your server list and check its status: 
```bash theme={null}
claude mcp list
```

The server appears with a status indicator:

| Status                   | Meaning                                                                                                                                                                       |
| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `✓ Connected`            | Ready to use. This is what you should see for `claude-code-docs`                                                                                                              |
| `! Needs authentication` | The server is reachable but needs a browser sign-in, or a token passed with `--header`. See [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in) |
| `✗ Failed to connect`    | Server didn't respond. See [Troubleshooting](#troubleshooting)                                                                                                                |
| `✗ Connection error`     | The connection attempt threw an error. See [Troubleshooting](#troubleshooting)                                                                                                |
| `⏸ Pending approval`     | A project-scoped server you haven't approved yet. See [Edit .mcp.json directly](#edit-mcp-json-directly)                                                                      |
Start a session and ask Claude to use the new server by name: 
```bash theme={null}
claude
```

```text theme={null}
Use the claude-code-docs server to look up what MCP_TIMEOUT does
```

<Info>
  You don't normally need to name a server in your prompt, since Claude chooses relevant tools on its own. Naming it here guarantees the demonstration goes through the new server rather than another tool, such as web fetch, that could answer the same question.
</Info>

The first time Claude calls the server, it asks for permission to use the new tool. Approve it to continue. The tool call in Claude's output is labeled with the server name, which is how you confirm the answer came from the MCP server rather than Claude's built-in knowledge.
This step is optional. When you're done experimenting, you can remove the server: 
```bash theme={null}
claude mcp remove claude-code-docs
```

<Note>
  Each connected server takes some space in [Claude's context window](./code-how-claude-code-works.md#the-context-window) because its tool names and server instructions load into every session. Removing servers you no longer use keeps that space free.
</Note>

Where servers are saved

The claude mcp add command writes the server's details to a configuration file. By default it registers the server at local scope: private to you, active only in the current project. Pass --scope user to register it once for all your projects, or --scope project to share it with teammates. Change server scope walks through both.

`claude mcp add` works the same in every shell, including PowerShell and Command Prompt. Inside a `claude` session, use the `/mcp` command to check and manage servers you've already added.

There are other ways to add a server, each covered later on this page:

Find your configuration on disk

The claude mcp add command writes the server to one of three scopes, stored across two files, depending on the --scope flag. You don't need to edit these files directly, but knowing where they are helps with debugging and version control.

Scope File Available to
local ~/.claude.json, under the entry for this project Only you, only this project. The default
project .mcp.json in your project root Everyone who clones the project
user ~/.claude.json, under the top-level mcpServers key Only you, all projects

On Windows, ~/.claude.json resolves to %USERPROFILE%\.claude.json, typically C:\Users\YourName\.claude.json. If you've set CLAUDE_CONFIG_DIR, Claude Code reads .claude.json from inside that directory instead.

Run claude mcp get claude-code-docs to see which scope holds a server's definition. For how the scopes interact when the same server is defined in more than one, see MCP installation scopes.

Change server scope

A server's scope is fixed when you add it, so changing scope means removing the entry and re-adding it at the new one. Both cases below start by removing the local entry from the first walkthrough, so the server has only one definition. If you already removed it at the end of that walkthrough, skip this command:

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

Use a server in all your projects

Re-add the server at user scope to make it active in every project you open, still private to you:

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

Share a server with your team

Re-add the server at project scope, which writes to .mcp.json in the project root:

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

Commit .mcp.json to version control. Teammates who clone the repository and start Claude Code see a prompt to approve the server, then it connects for them too.

Additional MCP server examples

The first walkthrough used a hosted server that connects without any sign-in. The examples below cover the other two common shapes, with the same add, check, use flow.

Add a local server

A local stdio server is a program Claude Code starts as a subprocess on your machine, rather than a service it reaches over a URL. Use one for tools that need access to local resources like a browser, your filesystem, or a database socket.

The Playwright MCP server is a good one to try: it gives Claude a browser it can navigate, click, and read, and it needs no account. It runs through npx, so it requires Node.js 18 or later.

Register the server with the command Claude Code should run to start it: 
```bash theme={null}
claude mcp add playwright -- npx -y @playwright/mcp@latest
```

This command differs from the hosted example in three ways:

* There's 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.
* `-y` tells `npx` to install the package without prompting.

Playwright drives whichever Chrome is already installed on your machine. To use a different browser, append `--browser` with the browser name, for example `--browser firefox`, after `@playwright/mcp@latest`.
The `Added` confirmation means the entry was saved, not that the command runs. Check the connection: 
```bash theme={null}
claude mcp list
```

The first check can show `✗ Failed to connect` while `npx` downloads the package, so wait a moment and run it again.
Give Claude a task that needs the browser: 
```text theme={null}
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 are labeled with the `playwright` server name and the action, like `browser_navigate`.

Try pointing it at your local dev server to check that a page still renders after a change, or have it walk through a bug report step by step.

Connect a server that requires sign-in

Hosted services like Sentry, Linear, and Notion run their MCP servers behind OAuth: you add the server's URL, then sign in through your browser.

The steps below use Sentry as the example. To connect a different service, substitute its URL, which you can find in the Anthropic Directory or the service's documentation.

The `add` command is the same as for the docs server, with Sentry's URL: 
```bash theme={null}
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
```

After adding, `claude mcp list` shows the server with `! Needs authentication`. That's expected: the next step completes the sign-in.
Start a Claude Code session and open the MCP panel: 
```text theme={null}
/mcp
```

Select `sentry` from the list, press Enter, and choose `Authenticate`. Your browser opens to Sentry's sign-in page. Approve the connection there.

Back in Claude Code, the server's status changes to connected. If sign-in fails or the browser doesn't open, see [Troubleshooting](#troubleshooting).
Ask Claude something that needs the service, like `What Sentry projects do I have access to?`, and look for tool calls labeled with the `sentry` server name in its output.

Servers that authenticate with a static token instead of OAuth take the token at add time with --header "Authorization: Bearer <token>". See the GitHub example for a worked version.

Edit .mcp.json directly

Every file in the scope table uses the same JSON format for server entries. This section edits .mcp.json, the project-scope file. It's the one most worth writing by hand because it's checked into the repository, where it doubles as configuration-as-code for your team.

Create .mcp.json in your project root. The example below defines both servers from this guide, the hosted docs server reached over HTTP and the Playwright server as a local stdio process:

{
  "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 server type:

  • For HTTP servers, url is the endpoint Claude Code connects to.
  • For stdio servers, command and args are the program it runs.

After saving the file, start a new Claude Code session in the project. Claude Code reads .mcp.json at startup.

The first time Claude Code sees a project-scoped server, it asks you to approve it. The prompt exists so a repository you clone can't launch processes on your machine without your consent. Approve the prompt, or run /mcp to approve later if you missed it.

Once you've approved, run /mcp and check that the servers show as connected. If one shows an error instead, see Troubleshooting.

Connect from other surfaces

This guide uses the claude mcp CLI commands, but every Claude Code surface can connect to MCP servers:

Troubleshooting

If a server doesn't connect, check its status with /mcp inside a session or claude mcp list from your shell, then match the symptom below. The /mcp panel also lets you reconnect or authenticate without leaving the session.

Claude Code didn't find any servers for the current directory. The most common causes: 
* You ran `claude mcp add` from a different project. Local-scoped servers are tied to the project where you added them: the repository root, or the exact directory if you weren't in a git repository. Re-add the server from the project you're in now, or add it with `--scope user` so it isn't tied to a project.
* You edited a configuration file at the wrong path. The correct files are `~/.claude.json` and `<project>/.mcp.json`. Claude Code doesn't read paths such as `~/.claude/config/mcp.json`, `~/.claude/mcp.json`, or `%APPDATA%\Claude\mcp.json`.
Both statuses mean the server didn't start or the URL didn't respond. They can also appear for HTTP servers that expect a token rather than the browser sign-in covered in [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in). 
For HTTP servers, confirm the URL is reachable from your machine:

```bash theme={null}
curl -I https://mcp.sentry.dev/mcp
```

In PowerShell, use `curl.exe` instead of `curl` so the request goes to the real curl binary rather than the `Invoke-WebRequest` alias.

The response tells you which kind of problem you have:

* A `404` or `405`: the server is up. Many MCP endpoints answer only POST requests, so this still confirms the URL is reachable from your machine.
* A `401` or `403`: the server is up and you need to authenticate. Use the browser sign-in in [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in), or for servers that take a token instead, like GitHub's, pass it with `--header "Authorization: Bearer <token>"` on the `claude mcp add` command.
* No response at all: check the URL and your network.

For stdio servers, run the configured command directly in your terminal to see the underlying error. For the Playwright server from this guide, run:

```bash theme={null}
npx -y @playwright/mcp@latest
```

What happens next tells you where the problem is:

* The command starts and waits for input: the server itself works. Run `claude mcp get <name>` and confirm the command shown there matches what you just ran. If the command shown differs from what you typed, you likely omitted the `--` separator before the server command. Remove the server and re-add it with `--` in place. If you wrote `.mcp.json` by hand, check its syntax and location.
* The command errors: the message names what's missing, such as Node.js or a browser.
The server took longer than the default 30-second startup timeout. A stdio server's first run can be slow while `npx` downloads the package. Increase the limit with the [`MCP_TIMEOUT`](./code-env-vars.md) environment variable, in milliseconds: 
```bash theme={null}
MCP_TIMEOUT=60000 claude
```

In PowerShell, set the variable before the command on the same line:

```powershell theme={null}
$env:MCP_TIMEOUT = "60000"; claude
```
You've already added a server with that name at the same scope. Either remove the existing entry first or choose a different name: 
```bash theme={null}
claude mcp remove claude-code-docs
```

If the name exists at more than one scope, `remove` reports `exists in multiple scopes`. Pass `--scope` to choose which copy to delete, for example `claude mcp remove claude-code-docs --scope local`.
Run `/mcp` inside a session and select the server to see its tool list. If the list is empty, the server started but didn't register any tools, which usually means it's missing a required environment variable such as an API key. 
Pass the variable with `--env KEY=value` on `claude mcp add`, or in the `env` field of the server's `.mcp.json` entry. The server's documentation lists the variables it needs.
Claude Code reads `.mcp.json` at session start. Exit and restart the session after editing the file. 
If your servers still don't appear, run `/mcp` and look for a parse warning. Claude Code skips malformed entries and shows the offending field there.

If you previously rejected the server when prompted, reset project approvals:

```bash theme={null}
claude mcp reset-project-choices
```
Run `/mcp`, select the server, and choose `Authenticate` again. If the browser doesn't open automatically, copy the URL shown in the terminal and open it manually. See [Authenticate with remote MCP servers](./code-mcp.md#authenticate-with-remote-mcp-servers) for fixed callback ports and pre-configured credentials.

Next steps

With one server connected, explore the rest of what MCP enables: