# How to Add an MCP Server to Claude Code (2026 Guide)

> Add an MCP server to Claude Code in one command — remote or local. Covers scopes, the .mcp.json file, verifying servers, and fixing connection errors.

Source: https://designrevision.com/blog/add-mcp-server-to-claude-code

---

To add an MCP server to Claude Code, run `claude mcp add` in your terminal: `claude mcp add --transport http <name> <url>` for a remote server, or `claude mcp add <name> -- npx -y <package>` for a local one. That single command is all it takes to give Claude Code a new set of tools — a database, a browser, your GitHub repos, or a component registry. This guide walks through both server types, how to scope them, where the `.mcp.json` config file lives, how to verify a connection, and what to do when one won't connect.

*Last updated: July 2026. Claude Code's MCP commands and flags change between releases; every command here was verified in July 2026 — run `claude --version` and check the official docs if something behaves differently.*

If you're still fuzzy on how MCP relates to plugins and skills, our [skills vs. plugins vs. agents vs. MCP breakdown](/blog/claude-code-skills-vs-plugins-vs-agents) explains where each fits. An **MCP server** is just a program that exposes tools; Claude Code connects to it, discovers those tools, and calls them during a task. There are two kinds — **remote** servers you reach over HTTP, and **local** servers Claude Code launches on your machine — and the setup differs slightly for each.

## Add a Remote MCP Server (HTTP)

Most hosted MCP servers are remote: you point Claude Code at a URL, and it connects over HTTP. The command is:

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

If the server needs authentication — most paid or account-scoped ones do — pass a bearer token in a header. Here's a real example adding **[DesignRevision MCP](/mcp)**, a server that installs [shadcn/ui components](/components) straight into your project:

```bash
claude mcp add --transport http design-revision https://mcp.designrevision.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"
```

Replace `YOUR_TOKEN` with the token from your account. Some servers use browser-based OAuth instead of a token — for those, add the server without a header, then run `/mcp` inside a Claude Code session to complete the sign-in. If your server speaks SSE rather than plain HTTP, swap `--transport http` for `--transport sse`.

Prefer raw JSON? `claude mcp add-json <name> '<json>'` takes the same configuration as a one-liner, which is handy when a vendor gives you a ready-made config block.

## Add a Local MCP Server (stdio)

Local servers run as a subprocess on your machine, communicating over stdio. Here, everything after `--` is the command Claude Code runs to start the server:

```bash
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/code
```

That adds the reference filesystem server, scoped to `~/code`. The `-- npx -y <package>` pattern works for most Node-based servers; Python servers use `-- uvx <package>` or `-- python -m <module>` instead.

When a local server needs a secret — an API key, say — pass it as an environment variable with `-e` **before** the `--`, so it never ends up in your shell history:

```bash
claude mcp add firecrawl -e FIRECRAWL_API_KEY=YOUR_KEY -- npx -y firecrawl-mcp
```

Remote servers are lower-maintenance (nothing to install or keep updated), while local servers give the agent direct access to your machine. Pick whichever the server you're adding supports.

## Choose the Right Scope: Local, Project, or User

Every `claude mcp add` accepts a `--scope` flag that decides *where* the server is available and who else gets it:

- **`--scope local`** (the default) — only you, only in the current project. Good for experiments and personal tools.
- **`--scope project`** — written to a `.mcp.json` file at the repo root that you commit, so your whole team gets the server automatically.
- **`--scope user`** — available in every project on your machine. Use it for general-purpose servers like GitHub or a docs server you want everywhere.

```bash
claude mcp add --scope user --transport http design-revision https://mcp.designrevision.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"
```

A common cause of "it worked yesterday, now it's gone" is adding a server in `local` scope and then switching projects — the server was never global. If you want it everywhere, use `user` scope.

## The .mcp.json Config File

Project-scoped servers live in a `.mcp.json` file at the root of your repository. You can create or edit it by hand instead of using the CLI — useful for code review and for keeping your team's server list in version control. The DesignRevision example looks like this:

```json
{
  "mcpServers": {
    "design-revision": {
      "type": "http",
      "url": "https://mcp.designrevision.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

Commit `.mcp.json` and every teammate who opens the project in Claude Code is prompted to enable the same servers. One caution: don't hard-code real secrets in a committed file — reference an environment variable, or keep token-bearing servers in `user` scope instead. Local and user-scoped servers are stored in Claude Code's own config outside the project, not in `.mcp.json`.

## List, Verify, and Remove Servers

After adding a server, confirm it actually connected:

```bash
claude mcp list
```

This prints every configured server and its status — a healthy one shows as connected, a broken one as failed. For a single server's details, use `claude mcp get <name>`. Inside a Claude Code session, type `/mcp` to view servers interactively, complete any OAuth sign-in, and see the exact tools each one exposes. To delete a server you no longer need:

```bash
claude mcp remove design-revision
```

## Troubleshooting: When an MCP Server Won't Connect

If `claude mcp list` shows a server as **failed**, work through these in order — they cover nearly every case:

- **Wrong URL or transport.** Double-check the endpoint and that you used `--transport http` (or `sse`) for a remote server. A remote URL added without `--transport` is a common miss.
- **Missing or expired token.** For servers behind auth, confirm the `Authorization: Bearer` header is present and the token is current. Re-run `/mcp` in a session to re-authenticate OAuth servers.
- **Wrong scope.** If the server isn't showing up at all, you may have added it in a different scope or project. Re-add it with `--scope user` to rule scope out.
- **Local server won't start.** For stdio servers, run the command after `--` directly in your terminal (e.g. `npx -y <package>`) to see the real error — usually a missing package or a bad path.
- **Need the full log.** Start Claude Code with the `--debug` flag to see the complete MCP connection handshake, which surfaces the underlying error when the summary isn't enough.

## Which MCP Servers Should You Add?

Adding the server is the easy part — choosing a good, focused set is what makes Claude Code genuinely more capable. GitHub, Playwright, Context7, and a database server cover most workflows, and **DesignRevision MCP** adds the one thing the others don't: installing real shadcn/ui components on request. For the full breakdown with an install command and honest verdict for each, see our roundup of the [best MCP servers for Claude Code](/blog/best-mcp-servers-for-claude-code). Resist the urge to add everything — a couple of servers the agent actually reaches for beats a dozen it ignores.

## Conclusion

Adding an MCP server to Claude Code comes down to one command — `claude mcp add` — plus a few choices: remote or local, which scope, and whether to keep the config in a committed `.mcp.json`. Once it's in, `claude mcp list` and `/mcp` are all you need to verify and manage it, and the troubleshooting checklist above resolves the rare case where a server won't connect. Start with one server that fills a real gap in your workflow, confirm it's connected, and build up from there.

---

## Related Resources

- [DesignRevision MCP — the shadcn/ui MCP server](/mcp)
- [Best MCP Servers for Claude Code (2026): Tested & Ranked](/blog/best-mcp-servers-for-claude-code)
- [How to Add an MCP Server to Cursor (2026 Guide)](/blog/add-mcp-server-to-cursor)
- [How to Add an MCP Server to Codex CLI (2026 Guide)](/blog/add-mcp-server-to-codex)
- [How to Add an MCP Server to Windsurf (2026 Guide)](/blog/add-mcp-server-to-windsurf)
- [Claude Desktop MCP Config: How to Add a Server (2026)](/blog/claude-desktop-mcp-config)
- [Claude Code Skills vs. Plugins vs. Agents vs. MCP](/blog/claude-code-skills-vs-plugins-vs-agents)
- [Claude Code Plugins: The Complete Guide](/blog/claude-code-plugins)
- [How to Install Claude Code Plugins](/blog/how-to-install-claude-code-plugins)
- [Browse the shadcn/ui component registry](/components)