# How to add MCP servers to Claude Code (step by step)

> Add MCP servers to Claude Code with claude mcp add: stdio and HTTP examples, local vs project vs user scope, .mcp.json, authentication, /mcp and safety tips.

Source: https://devaiper.com/blog/claude-code-mcp-servers
Published: 2026-10-08
Topics: Claude Code, MCP, Tutorial

**Short answer:** Add a server with claude mcp add. Use --transport http for remote servers and -- <command> for local stdio servers. Pick a scope (local, project or user), check status with /mcp, and only connect servers you trust.

An MCP server gives Claude Code new abilities: query a database, drive a browser, read your tickets. Adding one takes a single command. This guide covers the three kinds of server, where the config lives and how to keep it safe. If you want the background first, read [what is MCP](https://devaiper.com/blog/what-is-mcp).

## The three kinds of server

> **Diagram:** Three ways to connect an MCP server to Claude Code. A remote HTTP server uses claude mcp add with transport http and a URL. A local stdio server runs as a subprocess using claude mcp add with a dash dash separator and a command. A server defined in a project mcp.json file is shared with the team.
> Remote HTTP (--transport http <name> <url>) → Local stdio (<name> -- <command> [args]) → Shared in the repo (.mcp.json (project scope))
> Same client, three ways to register a server.

## 1. Add a remote (HTTP) server

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

For example, a hosted server:

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

If it needs a token in a header:

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

Many remote servers use OAuth instead. Add the server, then run `/mcp` inside Claude Code and follow the sign-in flow, or from the shell:

```bash
claude mcp login <name>
```

## 2. Add a local (stdio) server

A stdio server is a program Claude Code starts on your machine:

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

The `--` matters. **Everything after it goes to the server untouched**, so flags like `-y` are not parsed as Claude Code options. Put your own options (`--env`, `--scope`, `--transport`) before the name.

You can register the server you built yourself the same way. In the [MCP in Depth course](https://devaiper.com/courses/mcp-in-depth) that looks like:

```bash
claude mcp add repopilot -- npx tsx /absolute/path/to/server.ts
```

## 3. Pick a scope

| Scope | Loads in | Shared with team | Stored in |
|---|---|---|---|
| **local** (default) | This project only | No | `~/.claude.json` |
| **project** | This project only | Yes, via git | `.mcp.json` in the repo root |
| **user** | All your projects | No | `~/.claude.json` |

```bash
claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http my-crm --scope user https://crm.example.com/mcp
```

If the same name exists in several scopes, local beats project beats user. Servers from a shared `.mcp.json` require your approval before they run in an interactive session, which is a useful guard against a repo adding one behind your back.

## 4. The `.mcp.json` file

Project-scoped servers live in a file you commit:

```json
{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    },
    "database-tools": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": { "DB_URL": "postgresql://readonly:pass@host:5432/analytics" }
    }
  }
}
```

Do not commit real secrets. Use environment variables for tokens and passwords.

## 5. Manage your servers

```bash
claude mcp list          # everything configured
claude mcp get notion    # details for one server
claude mcp remove notion # remove it
```

Inside a session, type `/mcp` to see connection status, sign in with OAuth, enable or disable servers and check which tools they offer. Run `/context` to see how much context the loaded tools use.

## Keep the context small

Each server adds tool names to the model's [context](https://devaiper.com/blog/what-is-context-engineering). Claude Code defers the full tool schemas until a tool is needed, so idle servers are cheap, but a dozen overlapping servers still make tool selection worse. Keep the ones you use weekly and remove the rest. Picks to start with: [best MCP servers for developers](https://devaiper.com/blog/best-mcp-servers).

## Safety checklist

- **Trust the server.** Read its code or use a well-known publisher. Local stdio servers run with your user's permissions.
- **Treat fetched content as untrusted.** A server that returns web pages or issues can carry [prompt injection](https://devaiper.com/blog/mcp-security-risks).
- **Least privilege.** Use read-only database users and narrow tokens.
- **Prefer user or local scope** for personal tooling, and project scope only for servers the whole team should have.

Official reference: [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp).

## FAQ

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

Run claude mcp add. For a remote server use claude mcp add --transport http  . For a local stdio server use claude mcp add  --  [args]. Then run /mcp inside Claude Code to check its status.

### What are the MCP scopes in Claude Code?

Local (the default) loads the server only in the current project and is private to you. Project saves it in .mcp.json in the repo so the team shares it. User loads it in all your projects and is private to you.

### Where is the MCP configuration stored?

Local and user scope servers are stored in ~/.claude.json. Project scope servers are stored in a .mcp.json file at the project root.

### Why is there a -- in the claude mcp add command?

Everything after -- is passed to the server untouched, so Claude Code does not mistake the server's own flags for its options.

### Is it safe to add any MCP server to Claude Code?

No. Verify you trust each server before connecting it. Servers that fetch external content can expose you to prompt injection.