# How to add an MCP server to Claude Code

Canonical: https://theagenticweekly.com/guides/add-mcp-server-to-claude-code · Last verified: 2026-10-26 · Published: 2026-10-26 · Author: Agentic Weekly (operated independently from Texas, US) · Versions covered: Claude Code MCP docs as read on 2026-10-26; no Claude Code version recorded for these commands · Evidence: Reported (not run by us): from the Claude Code docs · Tools: claude-code

Checked 2026-10-26 by Agentic Weekly's editorial process: vendor docs re-read.

> To add an MCP server to Claude Code, run claude mcp add. For a remote server use --transport http and its URL; for a local one use --transport stdio and put the server command after --. Then run claude mcp list or /mcp to check that it connects. Reported from the docs, read 2026-10-26; not run by us.

## Pick a transport: remote HTTP or local stdio

An MCP server is a program that gives an AI agent tools; see [What is an MCP server?](https://theagenticweekly.com/what-is/mcp-server). Claude Code can talk to one over HTTP (a remote service) or stdio (a program it starts on your machine). Everything on this page is from Claude Code's MCP documentation, read 2026-10-26, and it is Reported: we have not run these commands.

Table: Transports in Claude Code

| Transport | Command shape | When to use | Source and date |
|---|---|---|---|
| HTTP | `claude mcp add --transport http <name> <url>` | The docs call HTTP the recommended option for remote servers and the most widely supported transport for cloud services | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 |
| stdio | `claude mcp add [options] <name> -- <command> [args...]` | A local process that Claude Code starts and talks to over standard input and output | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 |
| SSE | `claude mcp add --transport sse <name> <url>` | Deprecated per the docs; use HTTP where available. The docs say the HTTP command falls back to SSE for services that only expose it | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 |
| WebSocket | `claude mcp add-json <name> '<json>'` with `"type": "ws"` | For remote servers that push events; configured in `.mcp.json` or with `add-json`, authentication by header only | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 |

Docs change often and describe behaviour by Claude Code version, so re-check the source before relying on a flag.

## Add a remote server

Basic syntax and an example from the docs

```
claude mcp add --transport http <name> <url>
claude mcp add --transport http notion https://mcp.notion.com/mcp
```

With a bearer token (from the docs; replace the placeholder with your own token)

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

The docs say that when a server needs OAuth, you sign in from the `/mcp` panel inside a session, or run `claude mcp login <name>` in your shell; a `claude -p` or Agent SDK run cannot start the sign-in. For a worked token example, see [GitHub MCP server: how to set it up](https://theagenticweekly.com/guides/github-mcp-server).

Evidence: Reported. Source: [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26.

## Add a local server

Basic syntax and an example from the docs

```
claude mcp add [options] <name> -- <command> [args...]
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server
```

The docs explain that the `--` (double dash) separates Claude Code's own options, such as `--transport`, `--env` and `--scope`, from the command that starts the server; everything after it is passed to the server untouched. Without it, Claude Code would read the server's flags as its own. `--env` accepts several `KEY=value` pairs; if the server name comes straight after `--env`, the command reads the name as another pair and fails, so put another option, such as `--transport stdio`, between them.

A worked example for the reference Git server, built by combining the docs' command shape with that server's README. We have not run it as a command, though we did test the server itself outside Claude Code (see [Git MCP server: setup and what we tested](https://theagenticweekly.com/guides/git-mcp-server)):

Not run by us: the Git server added to Claude Code

```
claude mcp add --transport stdio git -- uvx mcp-server-git --repository /path/to/repo
```

Evidence: Reported. Source: [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26.

## Check it connected

Commands from the docs

```
claude mcp list
claude mcp get notion
/mcp   # inside a Claude Code session
```

- `claude mcp add` prints an `Added ...` line when the configuration was written; that is not proof the server connects.
- `claude mcp list` shows a health status next to each server, such as Connected, Needs authentication or Failed to connect.
- `claude mcp get <name>` shows details; for a failed server it shows the HTTP status or error code on an `Issue:` line.
- Statuses that report a configuration decision instead of a connection: Pending approval (a project server from `.mcp.json` you have not approved), Rejected, and Disabled for this project.

Evidence: Reported. Source: [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26.

## Scopes: local, project, user

Table: MCP installation scopes, per the docs

| Scope | Loads in | Shared with team | Stored in | Flag |
|---|---|---|---|---|
| local (default) | Current project only | No | `~/.claude.json` | `--scope local` |
| project | Current project only | Yes, via version control | `.mcp.json` in the project root | `--scope project` |
| user | All your projects | No | `~/.claude.json` | `--scope user` |

Project-scoped servers need your approval before Claude Code connects to them. The docs note that this "local scope" is different from general local settings, which live in `.claude/settings.local.json`. Source: [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26.

## Remove or disable a server

Command from the docs

```
claude mcp remove notion
```

The docs say that removing a remote server also deletes the OAuth tokens and client registration Claude Code stored for it. To switch a server off for one project without removing it, use the `/mcp` panel. Source: [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26.

## Troubleshooting

Table: Claude Code MCP problems and fixes

| Symptom | Likely cause | Fix | Source |
|---|---|---|---|
| A placeholder token is accepted at add time, then the server fails | `claude mcp add` saves the configuration without validating credentials | Run `/mcp` and check for a checkmark or an X; fix the token and add the server again. | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 |
| A JSON entry with a `url` is skipped with a message about a missing `type` | An entry with no `type` is read as a stdio server | Add `"type": "http"` (or `sse` or `ws`) to the entry. | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 |
| The server's own flags are rejected or misread | Without `--`, Claude Code parses the flags as its own | Put the whole server command after `--`. | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 |
| `--env` error when adding | The name directly after `--env` is read as another `KEY=value` pair | Place another option, such as `--transport stdio`, between `--env` and the name. | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 |
| A server needs authentication | The server answered 401 or 403 and Claude Code flagged it | Open `/mcp` and complete the sign-in; in `claude -p` runs, sign in from an interactive session first. | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 |
| A local npm-based server is older than expected | npm on an older Node installs older package versions without an error | Check `node --version`. Our study measured this for four packages, including the MCP filesystem server and the MCP Inspector. | [Our study: older Node installs older servers](https://theagenticweekly.com/research/older-node-silent-downgrades), 2026-10-25 |

## What we tested

Evidence: Reported (not run by us). We did not run `claude mcp add`, `list`, `get` or `remove` for this guide.

- What we ran: nothing for these commands. Our only Claude Code test is a separate smoke test on 2026-10-25 of a headless edit with a local model; see [the Claude Code test log](https://theagenticweekly.com/tests/claude-code). That task did not involve MCP servers.
- Reported, from the Claude Code MCP docs, read 2026-10-26: every command, flag, scope and status on this page.
- Not tested: OAuth sign-in, project approval prompts, plugins, managed configuration, WebSocket servers, Windows behaviour, and whether any listed server connects or works.

Table: Evidence by section

| Section | Evidence | Source |
|---|---|---|
| Transports, remote, local | Reported | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 |
| Check, scopes, remove | Reported | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 |
| Git server worked example | Reported (combination of two documents) | [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), read 2026-10-26 and [Git server README](https://github.com/modelcontextprotocol/servers/tree/main/src/git) |

## Related tools

- [Claude Code](https://theagenticweekly.com/tools/claude-code): Update now if you use the sandbox or run Claude Code on a cloud provider; skip if you wanted flashy new features, this is a hardening release. Tested (smoke test, 2026-10-25, local Qwen2.5-3B-Instruct, not vendor models).

## 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 <name> <url>; for a local one use claude mcp add --transport stdio <name> -- <command>. Then check with claude mcp list. This is from the Claude Code docs, read 2026-10-26; we have not run it.

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

Per the docs, local scope (the default) loads only in the current project and is private to you. Project scope stores the server in .mcp.json so your team shares it through version control. User scope loads in all your projects.

### How do I see which MCP servers Claude Code has?

Run claude mcp list for each server and a health status, claude mcp get <name> for details on one server, or /mcp inside a session. These commands are from the Claude Code docs, read 2026-10-26.

### How do I remove an MCP server from Claude Code?

Run claude mcp remove <name>, for example claude mcp remove notion. The docs say removing a remote server also deletes the OAuth tokens and registration Claude Code stored for it. We have not run this command.

### Why does my MCP server show as failed?

The docs say Failed to connect means Claude Code could not reach the server, and claude mcp get <name> shows the HTTP status or error. Common causes are a wrong token, a missing type on a JSON entry or a server command that does not start.

### Have you tested these commands?

No. We have not run claude mcp add, list, get or remove for this guide, so every command is copied from the Claude Code docs, read 2026-10-26. Our Claude Code test log covers a different task.

## Sources

- [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) (fetched 2026-10-26)
- [mcp-server-git README (for the worked example)](https://github.com/modelcontextprotocol/servers/tree/main/src/git) (fetched 2026-10-26)

## Related

- [Claude Code facts and sources](https://theagenticweekly.com/tools/claude-code)
- [Test log: Claude Code with a local model](https://theagenticweekly.com/tests/claude-code)
- [Best MCP servers](https://theagenticweekly.com/best/mcp-servers)
- [What is an MCP server?](https://theagenticweekly.com/what-is/mcp-server)
- [Guide: Git MCP server](https://theagenticweekly.com/guides/git-mcp-server)
- [Guide: GitHub MCP server](https://theagenticweekly.com/guides/github-mcp-server)
- [Guide: Playwright MCP server](https://theagenticweekly.com/guides/playwright-mcp-server)
- [Study: MCP server startup and call latency](https://theagenticweekly.com/research/mcp-servers-latency-and-failures)

## Changelog

- 2026-10-26: First published. Claude Code MCP docs read on this date; nothing was run.

## How to cite

Agentic Weekly, "How to add an MCP server to Claude Code", last updated 2026-10-26, https://theagenticweekly.com/guides/add-mcp-server-to-claude-code