Most “MCP doesn’t work” reports are one of five things. Start with the status line — it usually names the problem.
1. Read the status
claude mcp list
claude mcp get github
Lists every configured server with its health: ✔ Connected, ! Needs authentication, ✘ Failed to connect (with the HTTP status or error after it), ⏸ Pending approval (run claude to approve), ✘ Rejected, or ⊘ Disabled for this project. Inside a session, /mcp shows the same panel and lets you toggle servers per project.
2. Wrong scope
A server added with the default local scope lives in ~/.claude.json under the project path you ran the command in — it does not exist in other folders. --scope project writes .mcp.json in the repo (shared); --scope user makes it available everywhere:
claude mcp add --transport http --scope user context7 https://mcp.context7.com/mcp
If claude mcp list is empty in a new project, you added the server somewhere else.
3. Project servers wait for approval
Servers from a repo’s .mcp.json are only loaded after you approve them in an interactive session (a trust dialog). If you clicked “no” once:
claude mcp reset-project-choices
Then run claude in the project and approve. A server listed in the disabledMcpjsonServers setting stays rejected until you remove it there.
4. The command line itself
For stdio servers, everything after -- belongs to the server; without it Claude Code tries to parse the server’s flags as its own:
claude mcp add --transport stdio myserver -- npx -y @example/server --port 8080
Two more classics: a JSON entry with a url but no "type": "http" is rejected — add the type. And a pasted token with a trailing newline produces a header that never authenticates; trim it:
TOKEN=$(cat token.txt | tr -d '\n')
claude mcp add --transport http myserver https://example.com/mcp --header "Authorization: Bearer $TOKEN"
Claude Code also warns about leading/trailing whitespace in command, args, env and headers, and about ${VAR} references with no value — give them a fallback: ${API_KEY:-} or ${API_BASE_URL:-https://api.example.com}.
5. Slow start, big output
A server that installs on first run (npx …) can exceed the startup timeout:
MCP_TIMEOUT=10000 claude
Ten seconds instead of the default. A tool that returns huge payloads hits the output cap (25,000 tokens by default; warned at 10,000) — raise it with MAX_MCP_OUTPUT_TOKENS=50000 claude, or make the tool paginate.
Still stuck
Run the server by hand (npx -y @example/server) and watch its stderr — a missing binary, a bad API key or a Python version error shows up there long before Claude Code can tell you. On Windows, wrap npx servers as cmd /c npx … if the shell can’t find the shim.
Next: install an MCP server in Claude Code · connect a remote MCP server over HTTP · generate a config in the MCP config tool.