Claude Code MCP server not working? Fixes that actually work

Quick checklist

1. 1. Check the server is listed and connected
2. 2. Is it in the right scope (and folder)?
3. 3. Check the JSON
4. 4. Run the command yourself
5. 5. Environment variables and tokens
6. 6. Slow first start? Raise the timeout
7. 7. File tools can't see your folder
8. 8. Restart the session
9. Problems we actually hit in testing

1. Check the server is listed and connected

Run claude mcp list in the project folder. A working server shows ✔ Connected. That is the exact check our harness runs, for example playwright: npx -y @playwright/mcp@latest … - ✔ Connected. Use claude mcp get <name> for one server. Inside a session, type /mcp to see status and sign in to servers that need OAuth.

2. Is it in the right scope (and folder)?

Local scope is the default: the server loads only in the project folder where you ran claude mcp add, and is stored in ~/.claude.json under that project's path. Opening Claude Code in another folder hides it. Use --scope user for all projects, or --scope project to write .mcp.json in the project root and share it.

Project-scoped servers from .mcp.json need your approval in an interactive session first. If you declined, run claude mcp reset-project-choices.

3. Check the JSON

One stray comma breaks the whole file, and then no server loads. JSON doesn't allow trailing commas or comments, and every key and string needs double quotes. Check the file with:

python3 -m json.tool .mcp.json

It prints the file back if it's valid, or the line and column of the first error.

Adding servers with claude mcp add or claude mcp add-json avoids hand-editing ~/.claude.json.

4. Run the command yourself

Copy the exact command and args into a terminal and run them. A stdio server that starts correctly just waits silently for input (press Ctrl+C to stop). An error, a “command not found” or a crash here is the real problem, and the app's log will show the same thing.

Put the server command after -- so Claude Code doesn't read its flags: claude mcp add NAME -- npx -y PACKAGE --flag. This is the form we use for every test.

5. Environment variables and tokens

Pass secrets with --env KEY=value on claude mcp add. In .mcp.json, ${VAR} and ${VAR:-default} are expanded from your environment, so the file can be shared without the secret in it. Remote servers that use OAuth: sign in from /mcp. Note that claude -p runs have no /mcp panel, so sign in once in an interactive session first.

6. Slow first start? Raise the timeout

The first npx -y or uvx run downloads the package, which can take longer than the startup timeout. Set MCP_TIMEOUT in milliseconds, for example MCP_TIMEOUT=10000 claude. Large tool outputs are capped by MAX_MCP_OUTPUT_TOKENS (default 25,000).

7. File tools can't see your folder

Our tests: Filesystem (reference) failed in Claude Code until we fixed this. The server replaces the folder you passed on the command line with the client's own allowed folders (MCP “roots”). Start Claude Code with --add-dir /your/folder, or add the folder to permissions.additionalDirectories in settings.

8. Restart the session

Config changes apply to new sessions. Exit and run claude again, then check /mcp.

Problems we actually hit in testing

From our test runs on 2026-10-13 and 2026-10-14. These apply to every client, because the cause is in the server or the machine, not the app.

• Wrong Node version. context-mode needs Node 22.5 or newer and failed to start under Node 20.19 in our protocol check. Draw.io MCP also needs Node 22+. Check with node --version. If your default Node is older, install Node 22 and point command at its absolute path (for example /path/to/node22/bin/npx). That is how we made both pass.
• npx / uvx not found. Most servers we test start with npx -y … (needs Node.js) or uvx … (needs uv). Apps started from a dock or menu may not see the PATH your terminal uses. Run which npx / which uvx in a terminal and use that absolute path as command.
• The server needs something else running. Jupyter MCP only works with a running Jupyter server. Draw.io MCP acts on a live draw.io editor that has to be open. We failed Jupyter until a local JupyterLab was started.
• No Docker. Terraform MCP's documented quick start runs it in Docker. Where Docker isn't available we used HashiCorp's official release binary as the command instead.
• “Private IP” or SSRF refusals behind a proxy or VPN. On our test machine, DNS resolved public sites to 198.18.x addresses (a proxy's fake-IP range). Fetch (reference), DuckDuckGo search and Open-WebSearch have private-address guards that then refused every URL. If fetch tools fail only on one network, this is a likely cause. Each server documents its own override flag; only relax it on a network you trust.
• It's the website, not your setup. DuckDuckGo search sometimes got “No results” from DuckDuckGo's bot detection. That failed a search task in one of our Cursor runs (2026-10-13) even though the server was connected and working.
• One mode of a server fails while another works. Fetch (reference)'s default (readability) mode exited with an error on our machine; its raw=true option worked.

Sources

• Claude Code docs: Connect Claude Code to tools via MCP
• Claude Code docs: Settings
• MCP docs: Debugging
• MCP docs: Inspector

Links checked 2026-10-14. Items marked “Our tests” come from our own harness runs, shown on each server page with the date.