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:
https://.../mcp. The server runs somewhere else; Claude Code talks to it over HTTP. The docs recommend the HTTP transport for remote servers.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.
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"
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.
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
.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 mcp reset-project-choices resets those choices.${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 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.
claude mcp add-from-claude-desktop imports them (macOS and WSL).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.
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
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.