I've been watching people struggle with MCP servers on Reddit for months now. Same issues, over and over. The official docs read like a computer science textbook when what we need is a "here's what's actually going wrong" guide.

So here's everything I've learned from hundreds of "HELP! MCP servers not working!" posts.

First: How The Installation Command Actually Works

Everyone's copying commands without understanding what they're doing. Let me break down what each part actually does, because once you get this, 90% of your problems disappear.

The Basic Structure (What Each Piece Does)

claude mcp add [name] --scope user --env KEY=value -- npx -y [actual-server-package]

Let's decode this:

claude mcp add → The base command. This never changes.

[name] → Whatever YOU want to call it. Could be "filesystem", could be "banana". This is just your personal label.

--scope user → WHERE to save it. User = everywhere on your computer. Skip this and it only works in your current folder (stupid default).

--env KEY=value → Pass API keys or settings. Can have multiple. Each needs its own --env.

-- → THE CRITICAL SEPARATOR. Everything before = Claude config. Everything after = the actual command to run.

npx -y [package] → Runs the server from npm without installing globally. The -y means "don't ask questions."

Real Examples Showing The Variants

Simplest possible (no API key needed):

claude mcp add filesystem --scope user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

With one API key:

claude mcp add brave --scope user --env BRAVE_API_KEY=abc123 -- npx -y @modelcontextprotocol/server-brave-search

With multiple environment variables:

claude mcp add myserver --scope user \
  --env API_KEY=abc123 \
  --env API_SECRET=xyz789 \
  --env ENVIRONMENT=production \
  -- npx -y some-mcp-server

For a remote server (completely different structure):

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

Notice: transport type comes BEFORE the name for remote servers. I know, it's backwards. Everyone gets this wrong.

The Actual Issues Everyone's Having

Issue #1: "It worked yesterday and now it's broken"

What Reddit won't stop asking about: Server suddenly fails after working fine.

What's actually happening: The npm package updated and your local cache has the old version.

The fix everyone eventually finds:

claude mcp remove [servername]
claude mcp add [exact same command you used before]

This forces a fresh download. Yes, it's dumb that there's no update command. No, nobody knows why.

Issue #2: "Connection failed" (The Classic)

What you see: "Connection failed" error message that tells you nothing.

The actual causes (in order of likelihood):

  1. You forgot the double dash: Check your command. Is there a -- before npx? No? That's your problem.
  2. Wrong scope: You installed with default scope (local), moved folders, and now it's gone.
    • Fix: Reinstall with --scope user
  3. The server needs time to start: Some servers take 10+ seconds to initialize.
    • Fix: MCP_TIMEOUT=30000 claude mcp add ... (gives it 30 seconds)
  4. Port conflict: Something else is using the port.
    • Check: lsof -i :3845 (or whatever port)
    • Fix: Kill whatever's using it

Issue #3: "Authentication Required" (Even After Authenticating)

The Reddit classic: "I authenticated but it keeps asking me to authenticate!"

What's really happening: OAuth tokens expire. The servers don't tell you this.

The only fix that works:

  1. Type /mcp in Claude Code
  2. Click the server showing "authentication required"
  3. Re-authenticate
  4. If that fails, remove and re-add the entire server

Sentry and Notion are the worst for this. Their tokens expire randomly.

Issue #4: The Filesystem Permission Confusion

What everyone assumes: Give Claude access to ~/Documents and it can see everything inside.

Reality: You have to list EVERY folder you want to access.

Wrong:

claude mcp add filesystem --scope user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

Right (if you want multiple folders):

claude mcp add filesystem --scope user -- npx -y @modelcontextprotocol/server-filesystem \
  ~/Documents \
  ~/Desktop \
  ~/Downloads \
  ~/Projects

Each path needs to be separated by a space. Hidden folders need explicit inclusion. Subdirectories need their own entry if they're symlinked.

Issue #5: "But It Shows As Connected!"

The false positive everyone hits: /mcp shows green checkmark, but server doesn't work.

What "connected" actually means: The process is running. That's it.

What it doesn't mean:

  • Authentication is valid
  • API keys are correct
  • The server can actually do anything

How to actually test: Try to use it. Type @ and see if your server's resources show up. Green checkmark means nothing.

Issue #6: The Browser Tools Two-Terminal Dance

What the docs don't explain clearly: Browser tools need TWO separate things running.

Step 1 - Terminal window #1 (KEEP THIS OPEN):

npx -y @agentdeskai/browser-tools-server

Step 2 - Terminal window #2 (AFTER step 1 is running):

claude mcp add browser-tools --scope user -- npx -y @agentdeskai/browser-tools-mcp

Why everyone fails: They close terminal #1 or run both commands in the same terminal. You need that first terminal running forever.

Issue #7: API Keys in Plain Text (The Security Disaster)

What nobody realizes: Your API keys are sitting in plain text in ~/.claude.json.

What I've seen happen:

  • People screen-share with the file open
  • Commit .mcp.json to public repos
  • Copy their config to help someone and leak keys

The safer approach:

  1. Never use production keys
  2. Create a .env file with your keys
  3. Source it before starting Claude: source .env && claude
  4. Add .mcp.json to .gitignore immediately

The Debugging Checklist That Actually Works

When your MCP server breaks (not if, when), go through this in order:

  1. Type /mcp - What's the actual status?
  2. Check for the double dash - Is there -- before your npx command?
  3. Verify the scope - Did you use --scope user?
  4. Test with timeout - Add MCP_TIMEOUT=30000 to the start
  5. Remove and re-add - Seriously, this fixes 60% of issues
  6. Check background processes - Is that terminal still running?
  7. Look at the actual config - Open ~/.claude.json, is it malformed?

Command Structure Cheat Sheet

Local server, no API:

claude mcp add [yourname] --scope user -- npx -y [package-name]

Local server with API key:

claude mcp add [yourname] --scope user --env KEY_NAME=yourkey -- npx -y [package-name]

Local server with multiple settings:

claude mcp add [yourname] --scope user \
  --env SETTING1=value1 \
  --env SETTING2=value2 \
  -- npx -y [package-name] arg1 arg2

Remote HTTP server:

claude mcp add --transport http [yourname] https://server.url/path

Remote SSE server:

claude mcp add --transport sse [yourname] https://server.url/sse

With custom timeout (for slow servers):

MCP_TIMEOUT=30000 claude mcp add [rest of your command]

The Stuff Nobody Tells You

Servers don't update themselves. When something breaks randomly, remove and re-add.

The default scope is useless. Always use --scope user unless you're doing something specific.

Green checkmark means nothing. Test the actual functionality.

OAuth tokens expire. Usually at the worst time. Refresh them weekly.

Background processes die silently. That browser-tools-server terminal you minimized? Check if it's still running.

Port conflicts give useless errors. "Connection failed" usually means "port already in use."

The config files are just JSON. When all else fails, edit them directly.

Why Your Server Is Probably Broken Right Now

Based on every Reddit thread I've read:

  1. You forgot --scope user and wonder why it doesn't work in a new folder
  2. You closed the terminal running a background server
  3. Your OAuth token expired last week
  4. You're missing the -- separator
  5. You copy-pasted a command with smart quotes instead of regular quotes
  6. The npm package updated and you need to remove/re-add

The Bottom Line

MCP servers are powerful but fragile. The documentation makes them seem more complicated than they are. It's really just:

  • Understand the command structure
  • Always use --scope user
  • Don't forget the -- separator
  • Remove and re-add when things break
  • Keep background terminals open

Start with one server, get it working, then add more. And when someone on Reddit says "connection failed," just tell them to check for the double dash. It's always the double dash.