Adding MCP servers to Claude Code: remote, local and team setups that actually connect

Most "my MCP server doesn't work in Claude Code" problems come down to three small things: the wrong transport, the wrong scope, or a .mcp.json entry that Claude Code silently skips. This post walks through each one with commands you can paste, then shows how to confirm the server is really connected before you rely on it.

Everything below follows the official Claude Code MCP docs (code.claude.com/docs/en/mcp). Client CLIs change often, so if a flag behaves differently on your version, the docs win. The original, shorter version of this guide lives at AgentTask Atlas: How to add an MCP server to Claude Code.

1. Know which kind of server you have

Before typing anything, look at the server's README and find out which of these two it is:

• Remote (HTTP): the README gives you a URL such as https://.../mcp. The server runs somewhere else; Claude Code talks to it over HTTP. The docs recommend the HTTP transport for remote servers.
• Local (stdio): the README gives you a command such as npx some-package or uvx some-tool. Claude Code starts that process on your machine and talks to it over stdin/stdout.

Picking the wrong transport is the most common reason a server shows up as failed.

2. Add a remote server

The shape is claude mcp add --transport http <name> <url>. For example, Sentry documents a remote endpoint:

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

Servers that use OAuth (like that one) don't need a token on the command line. You sign in afterwards from inside a Claude Code session with /mcp.

If a server uses a fixed API token instead, pass it as a header:

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

3. Add a local (stdio) server

For stdio servers, everything after -- is the command that starts the server, passed through untouched. Claude Code's own flags (--transport, --env, --scope) go before the --:

claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest

With an environment variable the server needs:

claude mcp add --env API_KEY=your-key --transport stdio example -- npx -y @example/mcp-server

If you put --env after the --, it gets passed to the server as an argument instead of being set as a variable, which is an easy mistake to miss.

4. Choose a scope on purpose

Every claude mcp add writes to one of three scopes:

Scope	Who sees it	Where it lives
local (default)	Only you, only this project	~/.claude.json, under the project's path
project	Everyone who clones the repo	.mcp.json at the project root
user	Only you, in all your projects	your user config

A rule of thumb: servers with personal credentials go in local or user; servers the whole team should get go in project.

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

5. Sharing with a team: the .mcp.json gotcha

For a team setup you can commit .mcp.json at the repo root. The detail that trips people up: a remote entry needs "type": "http". An entry with a url but no type is read as a stdio server and skipped, with a configuration warning.

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Two more things worth knowing about project-scoped servers:

• Claude Code asks each developer for approval before using servers from a .mcp.json it hasn't seen before. claude mcp reset-project-choices resets those choices.
• .mcp.json supports ${VAR} and ${VAR:-default} expansion (in command, args, env, url and headers), so you don't have to commit secrets. The docs note that some credential variables are deliberately read as empty in a remote server's url and headers, so check that section if a header token doesn't arrive.

6. Confirm it actually connected

Adding a config doesn't mean the server works. Check:

claude mcp list          # status per server: ✔ Connected, ! Needs authentication, ✘ Failed to connect
claude mcp get sentry    # details for one server

Inside a session, /mcp shows the same status and is where OAuth sign-in happens. A "✘ Failed to connect" in claude mcp list means Claude Code couldn't reach that server, not that the list command itself failed.

Then do one real test: ask Claude to use a tool from that server and check the tool call in the transcript.

A few practical tips

• Already set up servers in Claude Desktop? claude mcp add-from-claude-desktop imports them (macOS and WSL).
• Slow-starting local servers: MCP_TIMEOUT=10000 claude raises the startup timeout to 10 seconds.
• claude mcp remove <name> removes a server; for remote servers it also deletes the stored OAuth tokens.
• Only connect servers you trust. The docs warn that servers which fetch external content can expose you to prompt injection. Read the permissions and the credentials a server asks for before adding it.

Finding a server for the task in front of you

If you're not sure which server to add, I keep a small, curated catalog of MCP servers and Agent Skills organized by dev task, with the install step, credentials, permissions and documented clients taken from each project's official README. Entries summarize official sources and are not hands-on tested, so always check the source repo.

• Servers whose docs include Claude Code setup: the Claude Code guide
• Compare by task, e.g. databases or debugging & observability
• Browser testing options such as Playwright MCP and Chrome DevTools MCP

The catalog is also available as a free, read-only remote MCP server (no account or key), which doubles as a quick way to test step 2:

claude mcp add --transport http agenttask-atlas https://agenttaskatlas.com/api/mcp

Setup for other clients: Cursor, VS Code, Claude Desktop.

---

Disclosure: I run AgentTask Atlas, the catalog linked above. This post was drafted with AI assistance and every command was checked against the official Claude Code docs before publishing.