Source: https://claudetutorial.com/guides/en-us/how-to-add-an-mcp-server-to-claude-code-commands-scopes-and-fixes

[Back to Guides](https://claudetutorial.com/guides/en-us)

Builders

# How to Add an MCP Server to Claude Code: Commands, Scopes and Fixes

October 27, 2026 11 min read

---

The usual way to connect Claude Code to a tool is to read three different setup pages, copy a command that is slightly wrong for your system, and wonder why nothing shows up. The real process is one command and one check, as long as you know which flavor of server you are adding.

> Every MCP server you add to Claude Code comes down to one command: claude mcp add, followed by how it connects.

This guide gives you the commands for the three kinds of server, explains the scopes that decide who gets the server, and covers sign-in, safety and the fixes for what goes wrong. If MCP is new to you, start with [What Is MCP?](https://claudetutorial.com/guides/en-us/what-is-mcp-the-model-context-protocol-explained-simply).

## What you need

- Claude Code installed and working. If not, see [Claude Code for Beginners](https://claudetutorial.com/guides/en-us/claude-code-for-beginners-install-sign-in-and-your-first-task)
- The server's address (for a remote server) or its start command (for a local one), from the service's own documentation
- An account with the service you are connecting

Connect a server when you find yourself copying data into the chat from another tool. Once it is connected, Claude can read from that system and act in it directly.

## Three kinds of server

Which command you use depends on how the server connects to you.

| Kind | How it connects | Use it for |
| --- | --- | --- |
| **Remote HTTP** | A web address on the internet | Most cloud services. The recommended choice |
| **Remote SSE** | A web address using an older method | Services that only offer it. Deprecated, so prefer HTTP where possible |
| **Local stdio** | A program that runs on your machine | Local files, databases and tools |

### Remote HTTP server

The basic form is the same for every service:

```
claude mcp add --transport http <name> <url>
```

A real example connects Notion:

```
claude mcp add --transport http notion https://mcp.notion.com/mcp
```

If the server needs a token, pass it as a header:

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

### Remote SSE server (deprecated)

The SSE method is deprecated, so use HTTP when the service offers it. If a service only has SSE, the command uses a different transport:

```
claude mcp add --transport sse asana https://mcp.asana.com/sse
```

### Local stdio server

A stdio server is a program that runs on your own machine, started by Claude Code. The basic form has a double dash, and everything after it is the command that starts the server:

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

An example that adds an Airtable server with an API key:

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

Do not forget the double dash

Everything after `--` is passed to the server untouched. Without it, Claude Code tries to read the server's own flags as its options, and the command fails in confusing ways.

## Check that it worked

After you add a server, check it from your terminal or from inside Claude Code.

Terminal

```
$ claude mcp list$ claude mcp get notion$ claude mcp remove notion
```

List every configured server, see the details of one, or remove one.

Inside a session, type `/mcp` to see the status of each server. You will see one of three states: connected, needs authentication, or failed to connect.

| Status | What it means | What to do |
| --- | --- | --- |
| Connected | The server is ready | Ask Claude to use it |
| Needs authentication | You have not signed in yet | Run `/mcp` and follow the browser login |
| Failed to connect | Claude Code could not reach or start it | See the fixes below |

## Sign in with OAuth

Many cloud servers use OAuth 2.0, the "sign in with your account" flow. The simplest path has two steps.

1. Add the server

   For example: `claude mcp add --transport http sentry https://mcp.sentry.dev/mcp`
2. Authenticate

   In Claude Code, run `/mcp` and follow the login steps in your browser.

From the shell you can also run `claude mcp login <name>` and `claude mcp logout <name>`. Tokens are stored securely and refreshed automatically. To revoke access, use **Clear authentication** in the `/mcp` menu.

## Scopes: who gets the server

When you add a server, you choose its scope. The scope decides which projects see it and whether your team shares it.

| Scope | Available in | Shared with your team | Stored in |
| --- | --- | --- | --- |
| **Local** (the default) | The current project only | No | `~/.claude.json` |
| **Project** | The current project only | Yes, through version control | `.mcp.json` in the project root |
| **User** | All your projects | No | `~/.claude.json` |

Choose one with the `--scope` flag:

```
# Project scope: shared with your team
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# User scope: available in all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
```

A project-scoped server writes a `.mcp.json` file at the root of your project, which you commit so everyone gets the same connection:

```
{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}
```

If the same server name appears in more than one scope, Claude Code connects once, using the definition from the highest-precedence source: local first, then project, then user.

Wins first Wins last

1. Local Only this project, only you, stored in ~/.claude.json
2. Project Shared with your team through .mcp.json
3. User All your projects, only you, stored in ~/.claude.json

Use project scope for tools the whole team needs, user scope for your personal tools, and local when you are testing.

When you open a project that has a `.mcp.json` from someone else, Claude Code asks for your approval before using its servers in an interactive session. To reset those approval choices, run `claude mcp reset-project-choices`.

## Popular servers you can add today

These examples come from the official documentation. Always read the service's own page for the current address.

| Service | Command |
| --- | --- |
| Sentry (errors) | `claude mcp add --transport http sentry https://mcp.sentry.dev/mcp` |
| Stripe (payments) | `claude mcp add --transport http stripe https://mcp.stripe.com` |
| GitHub (code reviews) | `claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"` |
| Notion | `claude mcp add --transport http notion https://mcp.notion.com/mcp` |
| PostgreSQL through DBHub | `claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"` |

For the database, notice the user name: `readonly`. Give Claude a database account that can only read. That one choice removes the most expensive mistake you could make.

You can also browse reviewed connectors in Anthropic's directory at claude.ai/directory. And if you added a connector in claude.ai, it is already available in Claude Code when you sign in with your Claude account.

## Stay safe

An MCP server gives Claude access to a system, and some servers fetch content from outside, such as web pages or tickets written by strangers.

Verify you trust each server

Servers that fetch external content can expose you to prompt injection: text written to trick an AI into doing something you did not ask for. Add only servers from sources you trust, and look at what Claude plans to do with them.

- The server comes from the service's own documentation, not a random post
- Databases use a read-only account
- Tokens go in headers or environment variables, never in a file you commit
- You work in a permission mode where you see what Claude does with the tools

That last point connects to how much Claude does without asking. See [Claude Code Permission Modes and Plan Mode, Explained](https://claudetutorial.com/guides/en-us/claude-code-permission-modes-and-plan-mode-explained) to decide it.

Inside Claude Tutorial

Trusting a tool is a decision, not a default

Judging which systems deserve access, and for which actions, is a skill that applies well beyond code, and the app practices it with real scenarios.

[GET IT ON Google Play](https://play.google.com/store/apps/details?id=com.claudetutorial.mobile)

## Limits and tuning

Two limits help explain behavior that otherwise looks odd.

- **Large results.** Claude Code shows a warning when a tool's output passes 10,000 tokens, and limits output to 25,000 tokens by default. To raise the limit, set the `MAX_MCP_OUTPUT_TOKENS` variable, for example `MAX_MCP_OUTPUT_TOKENS=50000`.
- **Slow servers.** To change how long Claude Code waits for a server to start, set `MCP_TIMEOUT`. For example, `MCP_TIMEOUT=10000 claude` allows ten seconds.

Tool search is on by default, so your context does not fill with every tool description at once. Run `/context` to see what is using space.

## When it does not work

| What you see | Likely cause | Fix |
| --- | --- | --- |
| The server is missing from `claude mcp list` | It was added in another scope or project | Run `claude mcp list` from the project where you added it, or add it with `--scope user` |
| `/mcp` shows needs authentication | You have not signed in | Run `/mcp` and follow the browser steps, or `claude mcp login <name>` |
| `/mcp` shows failed to connect | Wrong address, server down, or a start command that fails | Check the URL in the service's documentation. For a local server, run its command in your terminal to see the error |
| A local server's own flags are rejected | The double dash is missing | Add `--` before the server command |
| It works in one project but not another | Local scope applies to one project | Add it again with `--scope user`, or project scope for a team |
| Claude ignores a project server | Approval for the `.mcp.json` was declined | Run `claude mcp reset-project-choices` and approve again |
| Output is cut off | The 25,000 token default | Raise `MAX_MCP_OUTPUT_TOKENS` |

When none of that fits, ask Claude Code to help: paste the error and ask what it means. Running `/doctor` also checks your setup.

## Frequently asked questions

### How do I add an MCP server to Claude Code?

Run `claude mcp add --transport http <name> <url>` for a remote server, or `claude mcp add <name> -- <command>` for a local one. Then run `/mcp` inside Claude Code to check its status and sign in.

### Where does Claude Code store MCP servers?

Local and user scope servers are stored in `~/.claude.json`. Project scope servers are stored in a `.mcp.json` file at the root of your project, which you can commit.

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

Local applies to the current project and only to you. Project applies to the current project and is shared with your team. User applies to all your projects and only to you.

### How do I remove an MCP server?

Run `claude mcp remove <name>`. To sign out of a server without removing it, use `claude mcp logout <name>`.

### What does the double dash mean in claude mcp add?

It separates Claude Code's own options from the command that starts the server. Everything after it is passed to the server untouched.

### Are MCP servers safe?

Only as safe as the servers you choose and the access you give. Use trusted servers, read-only database accounts, and a permission mode where you can see what Claude does.

### Can I use my claude.ai connectors in Claude Code?

Yes. Connectors you add in claude.ai are available in Claude Code, in the terminal and in cloud sessions, when you sign in with your Claude account.

## Your Claude Code MCP checklist

- `claude mcp list` shows the server and `/mcp` shows it as connected
- You chose the scope on purpose: local to test, project for the team, user for yourself
- Credentials live in headers or environment variables, not in committed files
- Anything that touches data you cannot restore uses read-only access

## Continue reading

- [What Is MCP? The Model Context Protocol Explained Simply](https://claudetutorial.com/guides/en-us/what-is-mcp-the-model-context-protocol-explained-simply) for the idea behind it.
- [How to Add Connectors in Claude: Directory, Custom URL and Safety](https://claudetutorial.com/guides/en-us/how-to-add-connectors-in-claude-directory-custom-url-and-safety) for the same thing in the Claude apps.
- [Claude Code Best Practices: Habits That Get Better Results](https://claudetutorial.com/guides/en-us/claude-code-best-practices-habits-that-get-better-results) for working well once the tools are connected.
- [CLAUDE.md Explained: Teach Claude Code Your Project Once](https://claudetutorial.com/guides/en-us/claude-md-explained-teach-claude-code-your-project-once) to tell Claude how to use the connected tools in your project.