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

Posted on Oct 20 • Originally published at agenttaskatlas.com

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.

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

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

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 Enter fullscreen mode Exit fullscreen mode 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" Enter fullscreen mode Exit fullscreen mode 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 Enter fullscreen mode Exit fullscreen mode With an environment variable the server needs:

claude mcp add --env API_KEY = your-key --transport stdio example -- npx -y @example/mcp-server Enter fullscreen mode Exit fullscreen mode 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.

Every claude mcp add writes to one of three scopes:

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 Enter fullscreen mode Exit fullscreen mode 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" ] } } } Enter fullscreen mode Exit fullscreen mode Two more things worth knowing about project-scoped servers:

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 Enter fullscreen mode Exit fullscreen mode 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.

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.

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 Enter fullscreen mode Exit fullscreen mode 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.