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

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 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:

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, a server that installs shadcn/ui components straight into your project:

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:

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:

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.

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:

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

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:

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. 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
• Best MCP Servers for Claude Code (2026): Tested & Ranked
• How to Add an MCP Server to Cursor (2026 Guide)
• How to Add an MCP Server to Codex CLI (2026 Guide)
• How to Add an MCP Server to Windsurf (2026 Guide)
• Claude Desktop MCP Config: How to Add a Server (2026)
• Claude Code Skills vs. Plugins vs. Agents vs. MCP
• Claude Code Plugins: The Complete Guide
• How to Install Claude Code Plugins
• Browse the shadcn/ui component registry