Adding MCP servers to Claude Code and checking that they really connect

Adding an MCP server to Claude Code is one command, and the command almost always succeeds. That is the problem. claude mcp add prints a confirmation as soon as the configuration is written, whether or not the server behind it can be reached, authenticated, or started. The agent then carries on without the tools you expected, and the first sign of trouble is a response that ignores the database or issue tracker you just connected. This guide covers the parts of Claude Code MCP setup that decide whether a server actually works: the transport, the scope, authentication, and the checks that tell you the connection is real.

What MCP adds to Claude Code, and what it does not

MCP, the Model Context Protocol, is a standard way for an AI client to talk to outside tools. An MCP server exposes a set of tools, such as "query this database" or "create an issue", and Claude Code can call them during a session the same way it calls its built-in file and shell tools. The same server works with other MCP clients, which is why many servers publish setup instructions written for Claude Desktop or other editors rather than for Claude Code.

A common question is whether Claude Code and MCP are alternatives. They are not. Claude Code is the agent. MCP is how it reaches systems it cannot see from the local file system and shell: a hosted service with its own API, a database that needs credentials, a design tool, a monitoring dashboard. If a task only involves files in the project and commands you could run in the terminal, Claude Code can already do it without any server.

That distinction is worth holding onto before adding servers. Each connected server adds tool names to the session. Claude Code's tool search, which is on by default, defers the full tool definitions until they are needed, so only names and server instructions load at startup. That keeps the context cost low, but a long list of servers still gives the agent more choices to consider on every step. Connecting the three servers you use every week is different from connecting every server you have heard of.

Choose the transport the server actually speaks

Every server uses one of a few transports, and the command changes with each. The server's own documentation will say which one it supports.

Transport	How to add	Typical use	Notes
HTTP	claude mcp add --transport http <name> <url>	Hosted services	Recommended for remote servers, supports OAuth
SSE	claude mcp add --transport sse <name> <url>	Older hosted services	Deprecated in the docs, use HTTP where available
stdio	claude mcp add <name> -- <command> [args]	Local programs, scripts	Runs as a process on your Mac
WebSocket	claude mcp add-json with "type":"ws"	Servers that push events	Header authentication only

Remote HTTP servers are the simplest. The documentation's example connects Notion:

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

Recent versions of Claude Code try HTTP first and fall back to SSE automatically when a server only speaks SSE, so the http form usually covers both.

Local stdio servers have one detail that trips people up: the double dash. Everything before -- is an option for Claude Code, and everything after it is the command that starts the server. Without it, Claude Code tries to read the server's own flags as its own.

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

The documentation adds a second trap: if the server name comes directly after --env, the CLI reads it as another KEY=value pair and rejects it. Put another option, such as --transport stdio, between them.

When a server's instructions give only a JSON block, claude mcp add-json <name> '<json>' accepts it directly. A JSON entry that has a url but no type is read as a stdio server and skipped with an error, so add "type": "http" when copying remote configurations. If you already set servers up in Claude Desktop on the same Mac, claude mcp add-from-claude-desktop offers to import them. Server names added through these commands can contain only letters, numbers, hyphens, and underscores.

Decide where the configuration lives

Each server is added at one of three scopes, and the scope controls both where it loads and who else sees it.

Scope	Loads in	Shared with team	Stored in
Local (default)	Current project only	No	~/.claude.json
Project	Current project only	Yes, via git	.mcp.json in the project root
User	All your projects	No	~/.claude.json

The default is local, and that default explains a frequent complaint: a server works in one project and is missing in the next. It was added while the terminal was sitting in the first project, so it was saved under that project's path. Add --scope user for tools you want everywhere, such as a personal notes server, and --scope project for tools the whole team should share.

Project scope writes a .mcp.json file you can commit. Because a cloned repository could otherwise start arbitrary programs on your machine, Claude Code asks for approval before using servers from .mcp.json in an interactive session, and claude mcp list shows them as pending until you run claude in the folder and approve them. If you declined by mistake, claude mcp reset-project-choices clears those choices.

Two other details matter for shared configurations. First, .mcp.json supports environment variable expansion, so a team file can reference ${API_KEY} rather than containing the key. If a referenced variable is unset and has no default, Claude Code warns and loads the server with the text unexpanded. Second, when the same server name exists in several scopes, Claude Code uses one definition in full, with local winning over project and project over user. Fields are not merged, so a token set at user scope does not fill a gap in a project entry.

Turning a server off is different from removing it. Toggling a server off in the /mcp panel stops Claude Code from connecting to it in that project while keeping the configuration, and the choice is recorded per project in ~/.claude.json. This is the better option when a server is only noisy in one repository. claude mcp remove <name> deletes the entry, and for a remote server it also deletes the OAuth tokens and client registration Claude Code stored, so a later re-add starts the sign-in from scratch. When the same name exists at more than one scope, pass --scope to remove the definition you actually mean. Also avoid naming your own server after a built-in one, such as claude-in-chrome or computer-use: those names are reserved, and a configuration that uses them is skipped with a warning.

Authenticate remote servers

Many hosted servers require sign-in, and Claude Code supports OAuth 2.0 for them. Add the server, then either open the /mcp panel inside a session and follow the browser flow, or run the flow from your shell:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp login sentry

Tokens are stored and refreshed automatically. When a stored refresh token is rejected, Claude Code shows a notice pointing to /mcp, where Re-authenticate signs you in again. To remove access, use "Clear authentication" in the /mcp menu or claude mcp logout <name>.

Some servers use a static token instead, passed as a header with --header "Authorization: Bearer ...". In that case, a 401 or 403 response is reported as a failed connection rather than a sign-in prompt, because the credential to fix is the one you typed. Tokens pasted from a web page often carry a trailing newline. Claude Code warns about leading or trailing whitespace in headers and other values, but it does not trim them, so edit the configuration if that warning appears.

In non-interactive runs, such as claude -p in a script, there is no panel to complete a sign-in. Complete OAuth in an interactive session first, or the server's tools will be reported as unavailable in the scripted run.

Check that each server really connects

This is the step most setup guides skip. The documentation is explicit that the confirmation from claude mcp add only means the configuration was written. To find out whether the server works, check three things in order.

1. claude mcp list. It shows a health status beside each server: ✔ Connected, ! Needs authentication, or ✘ Failed to connect. For failures, recent versions append the detail, such as the HTTP status or error code. A pending status for a .mcp.json server means it has not been approved yet, which is a configuration state rather than a connection result.

2. claude mcp get <name>. This shows one server's full configuration and, when it has failed, an Issue: line with the reason. It also shows WebSocket servers, which do not appear in claude mcp list at all.

3. /mcp inside a session. The panel lists every server with its tool count and flags servers that advertise tools but expose none. A server that shows as connected with zero tools is the quietest failure of all, and the panel is where it becomes visible.

If a local server fails to start, run Claude Code with --debug='mcp,startup' to see the startup log for MCP servers. A slow server can be given more time with the MCP_TIMEOUT environment variable, for example MCP_TIMEOUT=10000 claude for 10 seconds. Tools that return very large results trigger a warning above 10,000 tokens and are limited to 25,000 tokens by default. MAX_MCP_OUTPUT_TOKENS raises that limit.

Finally, ask the agent to use the server for something small and verifiable, like listing the tables in the connected database. A real answer from the real system is the only check that covers the whole path.

Keep servers tied to the right project

Because local scope is the default, where you launch Claude Code decides which servers load. Running it from your home folder rather than the project folder means project-scoped and local-scoped servers for that project are missing, and the session looks as if the setup failed. The same thing happens when a terminal tab is left in the wrong directory after a cd.

A dependable routine is to open the project folder first, start the terminal there, and only then launch the agent. When that routine involves switching between a file browser and a separate terminal window, the working directory is easy to get wrong. A file manager with a built-in terminal starts the shell in the folder you are already looking at. The features page shows how that works, and the FAQ covers the common questions about using it with command-line agents.

What to set up first

Pick the one MCP server you would use this week, add it with the right transport and --scope chosen deliberately, then run claude mcp list and /mcp to confirm it shows as connected with a non-zero tool count before relying on it. If you want the project folder and the terminal that runs the agent in the same window, Atriens is built for that.