MCP Setup Troubleshooting Guide

Something's not working. Don't panic—most MCP issues have simple fixes. This guide covers the most common problems and their solutions. Find your issue, follow the fix, and get back to work.

The Quick Diagnostic

Before diving into complex fixes, check these 4 basics. 90% of issues are here.

Is Claude Desktop running? (The website claude.ai doesn't support MCP yet)

Did you restart Claude after editing the config file? (Required for changes to apply)

Is your config file in the right folder?

Is the config file valid JSON? (No missing commas or brackets)

Issue: Claude Doesn't Show My Tools

Symptoms: You added code to the config file, but when you open Claude, there's no "plug" icon, or it doesn't know about your tools.

Fix 1: Restart Claude Desktop Completely

Minimizing isn't enough. You must fully quit the application.

Mac: Click Claude in the menu bar → Quit Claude (Cmd+Q)
Windows: Right-click the Claude icon in the system tray (bottom right) → Quit

Fix 2: Verify Config File Location

Ensure the file is named exactly claude_desktop_config.json and is in:

MacOS~/Library/Application Support/Claude/

Windows%APPDATA%\Claude\

Pro Tip: Run code %APPDATA%\Claude in terminal to open it quickly.

Fix 3: JSON Syntax Errors

A single missing comma will break the entire file. Copy-paste your config into a validator like jsonlint.com to check it.

Issue: "Connection Refused" / Red Error Icon

Symptoms: You see a red plug icon or an error message saying Claude couldn't connect to the server.

Fix 1: Install Node.js

Most MCP servers need Node.js to run. If you skipped this step, nothing will work.

node --versionRun this in terminal to check

If it says "command not found", download from nodejs.org.

Fix 2: Use "Absolute Paths"

Sometimes Claude doesn't know where `npx` or `node` is installed. Try using the full path in your config.

// Instead of "command": "npx"

"command": "C:/Program Files/nodejs/npx.cmd" (Windows)

"command": "/usr/local/bin/npx" (Mac)

You can find the path by running where npx (Windows) or which npx (Mac) in terminal.

Issue: Constant "Sign In" Requests

Symptoms: Every time you restart Claude, it asks you to sign in to Google/Slack again, or the sign-in page doesn't open.

The Fix: Check Browser Defaults

The MCP server tries to open your default browser to authenticate. If you use a strict browser (like Arc or Brave) or have pop-up blockers, it might fail. temporarily set Chrome or Safari as default to complete the setup.

Advanced: Checking Logs

If you're still stuck, Claude processes have logs. Here is how to find them.

# Mac Logs

tail -f ~/Library/Logs/Claude/mcp.log

# Windows Logs

Get-Content -Path "$env:APPDATA\Claude\logs\mcp.log" -Wait

Still Stuck?

Setup issues can be frustrating because every computer is slightly different.

Try the Quick Start Kit Ask in Mastery Community

The Quick Start Kit includes a reliable config file that fixes 99% of syntax errors.