How to Add an MCP Server to Claude Code: A Step-by-Step Guide

If you want to know how to add an MCP server to Claude Code, the short answer is one command: claude mcp add. The longer answer — which transport to pick, which scope to store it in, and what to do when the server shows failed — is where most people get stuck. I build openseek, a TUI coding agent, so I wire up MCP servers constantly. This guide is the setup I actually run, verified against the Claude Code docs as of July 2026.

If you're still fuzzy on what these servers even are, read what is an MCP server first — this post assumes you just want the wiring.

Step 1: Pick a server

An MCP server is a small program that exposes tools (and sometimes data) to Claude over the Model Context Protocol. There are two flavors you'll meet:

• Local (stdio) servers run as a process on your machine — usually launched via npx, python, or uvx. Good for filesystem access, local databases, and anything that shouldn't leave your laptop.
• Remote (HTTP) servers are hosted URLs you connect to over the network, often behind OAuth. Think Notion, Sentry, Stripe, GitHub.

For a curated list of what's worth installing, see the best MCP servers for 2026. For this walkthrough I'll show one of each.

Step 2: Add it with claude mcp add

Run this from your terminal (not inside the Claude Code REPL). The base form for a local stdio server uses a -- to separate Claude's own flags from the command that launches the server:

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

Everything after -- is passed to the server untouched. A concrete example — a database server via npx:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub

For a remote HTTP server, you point at a URL instead:

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

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

Need to pass a header (for example an API token)? Use --header (short form -H):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

One accuracy note worth internalizing: claude mcp add saves the config without validating credentials. A placeholder token is accepted at add-time and only fails when Claude actually tries to connect. So a clean "added" message is not proof it works — Step 4 is where you confirm.

Step 3: Understand transports and scope

Transports are how Claude talks to the server:

• stdio (default) — launches a local process, talks over stdin/stdout.
• http — the current recommended transport for remote servers; supports OAuth. In JSON config the type field also accepts streamable-http as an alias, so configs copied from a server's docs work unchanged.
• sse — Server-Sent Events. Still supported (--transport sse), but it's the older remote transport being superseded by http. Prefer http for anything new.

Scope decides where the config is stored and who sees it. Use -s / --scope:

• local (default) — private to you, only in the current project. Stored in ~/.claude.json. This is what you get if you pass no scope flag.
• project — shared with your team via a .mcp.json file committed at the repo root.
• user — available to you across all your projects.

So to install a server for your whole team, commit it to .mcp.json:

claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

The resulting .mcp.json is designed to be checked into version control. Heads up: for security, Claude Code prompts each teammate for approval before using a project-scoped server, and in a freshly cloned (untrusted) repo those servers sit at ⏸ Pending approval until someone runs claude and accepts the workspace trust dialog. That's expected behavior, not a bug.

Step 4: Verify it connected

From your terminal, list and inspect what you've added:

claude mcp list
claude mcp get notion

Then, inside a Claude Code session, run the slash command:

/mcp

The /mcp panel shows each server's status and the tool count next to it. You want connected. A server with bad credentials or a wrong URL shows failed. /mcp is also where you complete OAuth login for remote servers that require it — run it and follow the browser flow.

Step 5: Use its tools

Once a server is connected, its tools are just available to Claude — you don't invoke them by name. You describe intent in plain language and Claude picks the tool:

"Check Sentry for errors on the checkout service in the last 24 hours and open a GitHub issue summarizing the top one."

That single sentence can span two MCP servers. This is the same mental model as Claude Code skills — you install a capability once, then just ask. (Skills and MCP overlap but aren't the same thing; more on the skills shelf below.)

Troubleshooting: "server not connecting"

If /mcp shows failed or the server never leaves pending, work through these in order:

1. Bad credentials. Since add doesn't validate, a typo'd token surfaces only here. Re-check the header or env var, then remove and re-add: claude mcp remove github then add again.
2. OAuth not completed. For remote servers requiring OAuth 2.0, the connection stays incomplete until you run /mcp and finish the browser login.
3. Pending approval in a cloned repo. Project-scoped .mcp.json servers won't connect in an untrusted workspace. Run claude interactively and accept the trust dialog. To reset earlier approval choices: claude mcp reset-project-choices.
4. Wrong transport. If a remote server's docs mention streamable-http, use --transport http — they're the same thing.
5. Reconnect drops. HTTP/SSE servers auto-reconnect with backoff (up to five attempts); after that they're marked failed and you retry from /mcp. Stdio servers are local processes and are not auto-reconnected — if the process died, re-adding relaunches it.
6. Empty URL. A remote entry with a blank url shows as not configured and Claude won't try to connect. Set the url.

When in doubt, claude mcp get <name> prints the exact stored config so you can eyeball the transport, URL, and scope.

That's the whole loop: pick a server, claude mcp add, choose transport and scope, verify with /mcp, then just talk to Claude. If you're assembling a broader toolkit, MCP servers pair naturally with skills — browse the skills shelf for curated, install-once capabilities that complement your MCP setup.

Want the signal without the noise? Every week I distill the MCP releases, new servers, and Claude Code changes actually worth your attention into one calm digest. Subscribe to the weekly and skip the doomscroll.