MCP Server Not Working? 5-Minute Fix Checklist

Q: What does MCP error -32000 mean?

In the official SDKs, -32000 means "Connection closed": the server went away before it answered. For a local server, the process usually exited because the command wasn't found, a key was missing, or it crashed. Read the server's stderr log for the real reason.

Q: Why is my MCP server not working in Claude Code?

Run claude mcp list or /mcp to see each server's status, then claude mcp get for the error detail. Failed to connect means the command or URL is wrong; connected with no tools usually means a missing environment variable. Claude Code versions before v2.1.302 also showed tools fetch failed for some servers on the 2026-07-28 spec, so update first.

Q: Where are the Claude Desktop MCP logs?

~/Library/Logs/Claude on macOS, %APPDATA%\Claude\logs on Windows and ~/.config/Claude/logs on Linux. mcp.log covers connections; mcp-server- .log holds each server's own output.

On this page

MCP Server Not Working? A 5-Minute Checklist and Error Fixes (Nov 2026)

When an MCP server isn't working, check six things in order: does the command start, does the server answer the handshake, does tools/list return tools, is it signed in, is it timing out, and is the tool itself returning an error. Most failures are the first one: a command, path or environment variable the app can't see.

This is one of the most common complaints on Reddit. An r/mcp post said "1 in 9 servers in the official MCP registry is broken", after checking whether each one answered the handshake and listed its tools (thread). Others are about a single app or server: tools not loading in Claude Code (r/ClaudeAI), "Claude MCP not working?" (r/framer), "Autodesk Revit MCP not working" (r/Revit), and Atlassian MCP timeouts and outages (r/atlassian, again). The checklist below works for all of them.

The 5-minute checklist

Tick each step off as you go. The first one that fails is your problem.

1. Does the server start at all?

Local (stdio) server: copy the exact command and args from your config and run them in a terminal. A working stdio server starts and then sits there waiting for input. If it prints an error instead, that error is your answer: Node missing, a wrong path, a missing API key.

If it works in your terminal but not in the app, the app is starting it differently:

Paths. The app may start the server in a different folder (the MCP docs say it can be / on macOS), so relative paths like ./data break. Use absolute paths in command, args and any .env file (MCP debugging guide).
Environment variables. Servers started over stdio "inherit only a limited subset of environment variables automatically", so a key you exported in your shell may not reach the server. Put it in the server's env block instead (same page). Keep real keys out of shared config files; see MCP API keys in config files.
Restart properly. Claude Desktop reads its config only at start, and closing the window is not enough: quit it fully and reopen it.

Remote (HTTP) server: check the URL answers at all. Claude Code's docs suggest curl -I <url> (use curl.exe in PowerShell). A 404 or 405 still means the server is up, since many MCP endpoints only answer POST. A 401 or 403 means it's up and wants you to sign in (step 4). No response means a wrong URL, a network problem or an outage (Claude Code MCP quickstart).

2. Does it answer the handshake?

Starting is not the same as speaking MCP. Test the server outside your app with the official MCP Inspector. Its CLI has a connect-only probe:

npx @modelcontextprotocol/inspector --cli node build/index.js --method initialize

Swap node build/index.js for your server's command, or put a URL there for a remote server. If this fails, the server is broken, not your app config.

Two things changed in the current spec (2026-07-28) that matter here. The old initialize handshake is gone: every request now carries its protocol version and client capabilities, and servers describe themselves through a new server/discover method (changelog). A version mismatch now comes back as error -32022 (UnsupportedProtocolVersion) listing the versions the server does support. Old and new servers and clients are meant to fall back to each other, but a client or server that only speaks one era will fail against the other. Updating the app, or the server, is often the whole fix.

The most common cause on a local server: it prints logs to stdout. The spec says "The server MUST NOT write anything to its stdout that is not a valid MCP message" (stdio transport). One stray console.log or print() breaks the stream. Logs go to stderr.

3. Does `tools/list` return any tools?

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

An empty list from a server that started fine usually means it needs something it didn't get. Claude Code's docs say an empty tool list "usually means it's missing a required environment variable such as an API key" (quickstart). Some servers only register tools once a key is set, or hide tools behind a URL parameter or a setting. Check the server's README for both.

If the Inspector shows tools but your app shows none, the problem is in the app. See the Claude Code and Cursor sections below.

4. Is it signed in?

401, Needs authentication, or a CLI exit code 3 from the Inspector: the server wants you to sign in. Do the OAuth sign-in from the app (in Claude Code, /mcp then Authenticate), or add the token header the server's docs ask for.
Signed in before, failing now: the token expired or was revoked. Sign out and back in. In Claude Code, /mcp has Re-authenticate and Clear authentication.
Pasted a token and it's rejected: check for a trailing space or newline. Claude Code warns about hidden whitespace in claude mcp list and /mcp.

How sign-in is supposed to work, and what a well-built server does on a bad token, is in MCP authentication explained.

5. Is it timing out?

A server that connects but fails on long jobs is a timeout, not a broken server. Startup timeouts and tool-call timeouts are separate settings. In Claude Code, startup is 30 seconds by default and MCP_TIMEOUT raises it, for example MCP_TIMEOUT=60000 claude. A first run can be slow while npx downloads the package. For tool calls, see MCP tool call timeout.

6. Is the tool returning an error?

If the server connects, lists tools and runs them, but a tool keeps failing, read the error text the tool returns. A tool that fails on bad input is different from one that fails because a key was revoked, and an agent will happily retry both. See MCP tool errors: why your agent keeps calling a failing tool.

MCP error codes and what they mean

MCP uses JSON-RPC 2.0 error codes. The ones you'll actually see:

Error	What it means	What to check
`MCP error -32000: Connection closed`	The connection to the server closed before an answer came back. Usually the server process exited	Step 1: run the command by hand and read the server's log (next section)
`MCP error -32001: Request timed out`	The client gave up waiting. The TypeScript SDK's default is 60 seconds per request	Step 5 and MCP tool call timeout
`-32700` Parse error	Something sent text that isn't valid JSON	A local server printing logs to stdout (step 2)
`-32600` Invalid request	The message isn't a valid JSON-RPC request	A client or server bug: update both, then report it
`-32601` Method not found	The server doesn't support that method	An old server getting a new-spec request, or the server doesn't offer that feature (prompts, resources)
`-32602` Invalid params	Bad arguments, an unknown tool, or a missing required field	The tool's input; in the 2026-07-28 spec this also covers "resource not found" and requests missing the protocol version
`-32603` Internal error	The server hit an error it didn't handle	The server's own log (stderr). This is a server bug; report it with the log
`-32021` MissingRequiredClientCapability	The server needs a feature your app didn't offer, such as elicitation	Use a client that supports it, or a server version that doesn't need it
`-32022` UnsupportedProtocolVersion	Your app and the server don't share a protocol version	Update the app or the server; the error lists the versions the server supports
Claude Code: `connection closed before the tool call was answered`	A remote server dropped the connection mid-call, so Claude Code can't tell whether the tool ran	Check whether the action happened before running it again

Where these come from: -32700 and -32600 to -32603 are the standard JSON-RPC codes. -32020 to -32099 are reserved for the MCP spec itself, which defines -32020, -32021 and -32022 (MCP spec, error codes). -32000 and -32001 are not spec codes at all. They are labels the official SDKs use for their own local errors: the TypeScript SDK defines ConnectionClosed = -32000 and RequestTimeout = -32001, and the Python SDK uses -32000 for a closed connection too (TypeScript SDK source). The spec now marks -32000 to -32019 as legacy and says receivers "MUST NOT assume any specific meaning" for them, so another client can use -32000 for something else. Read the message next to the number.

MCP error -32000: connection closed

It's the vaguest error you'll see, because it says what happened but not why. Your app started the server (or connected to it), and the connection ended before the server answered. For a local server, that almost always means the process exited. Common reasons, most likely first:

The command isn't found. The app couldn't run npx, uvx, node or python, often because the app doesn't see the same PATH as your terminal. Use the full path to the program. On Windows, Claude Desktop's docs cover an ENOENT error mentioning ${APPDATA}: add the expanded APPDATA value to the server's env, and check that npm is installed globally (connect local servers).
The server crashed on start, usually a missing API key or a wrong path. Running the command by hand (step 1) shows the crash.
The server wrote to stdout and broke the stream (step 2).
Wrong runtime version. A server built for a newer Node or Python exits on an older one. The error is in the server's stderr.
A remote server dropped the connection: a restart, a deploy, an outage, or your laptop going to sleep.

To see the real reason, read the server's stderr. Every client below keeps it somewhere.

Claude Desktop MCP not working

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, ~/.config/Claude/claude_desktop_config.json on Linux. Check the JSON is valid: a missing or trailing comma is an easy mistake to miss.
Logs: ~/Library/Logs/Claude (macOS), %APPDATA%\Claude\logs (Windows), ~/.config/Claude/logs (Linux). mcp.log has connection failures; mcp-server-<name>.log has that server's stderr. On macOS, follow them live with tail -n 20 -F ~/Library/Logs/Claude/mcp*.log.
Check what loaded: click the + ("Add files, connectors, and more") in the chat box and hover over Connectors to see connected servers and their tools.
After any change: quit Claude Desktop fully and reopen it.
Still stuck: the MCP docs show how to turn on DevTools in Claude Desktop with a developer_settings.json file containing {"allowDevTools": true}, then Command-Option-I (macOS) or Ctrl+Alt+I (Windows) to see client-side errors.

All of the above is from the MCP debugging guide and the local servers guide.

Claude Code MCP server not working

Run claude mcp list in your shell or /mcp in a session. Each server shows a status such as ✔ Connected, ! Needs authentication or ✘ Failed to connect, and claude mcp get <name> shows the error detail the server returned (Claude Code MCP docs). Then:

Failed to connect: run the server's command by hand (step 1). For remote servers, check the URL with curl -I.
Connected, but no tools: select the server in /mcp to see its tool list. Empty usually means a missing environment variable. Claude Code versions before v2.1.302 also showed tools fetch failed for some servers on the 2026-07-28 spec; updating fixes that (quickstart).
Several servers down: /mcp reconnect all retries every failed server (Claude Code v2.1.284 or later).
Need the full log: start claude --debug. The log is written to ~/.claude/debug/<session-id>.txt.

Claude Code has a lot more of these, including .mcp.json in the wrong place and servers waiting for approval. They're in the table in Claude Code MCP troubleshooting.

MCP tools not loading in Cursor ("0 tools enabled")

Cursor can show a server as connected, with a green dot, and still list 0 tools. Work through it in this order:

Read the MCP logs. Open the Output panel (Cmd+Shift+U on Mac) and pick MCP Logs from the dropdown. Cursor's docs say the logs "show server initialization, tool calls, and error messages" (Cursor MCP docs). If the log shows the server found its tools, the problem is on Cursor's side.
Check the toggles. Open Customize, find the server, and make sure it's switched on, along with any of its tools Cursor lists.
Toggle the server off and on, then start a new chat. A chat that was open before the tools loaded may not see them.
Test outside Cursor with the Inspector (step 3). If tools/list is empty there too, it's the server.

Two known Cursor bugs fit this symptom, both confirmed by Cursor staff on its forum. In May 2026 a server whose tools/list reply was about 287 KB (each tool repeated a large output schema) showed 0 tools, though the logs listed all 14; staff called it "a bug on our side" (thread). In August 2026, servers registered by an extension stayed at "0 tools enabled" until the extension source was toggled off and on in the server's settings (thread). If yours matches, update Cursor first. If you build the server, a smaller tool list helps every client, not just Cursor.

MCP server disconnected mid-session

Remote servers. Claude Code retries a dropped remote server up to five times with exponential backoff, and retries a failed first connection up to three times. If it still fails, it marks the server failed and you reconnect from /mcp.
Local servers. A stdio server that disconnects has usually exited. The spec says that if the process "exits unexpectedly, the client SHOULD restart it", but clients differ, so restart it yourself and read its stderr to see why.
Your computer slept. Claude Code reports a timeout when the clock jumped during a connection. Reconnect once the machine is awake.
The service is down. If a hosted server works one day and times out the next for everyone, as in the Atlassian threads above, it's an outage. Check the vendor's status page before changing your config.

Before you re-run a tool that was cut off, check whether it already did its job. A dropped connection doesn't tell you whether a write happened, and running it again can create a second issue, email or payment.

When the server is the problem

Sometimes nothing on your side is wrong. The server is abandoned, was built for an older spec, or breaks the stdout rule. Signs it isn't you:

The Inspector fails the same way your app does.
The repo hasn't had a commit in months and has open issues describing your error.
The README's setup steps no longer match the package.

Don't fix a broken server by turning off sign-in or by running a "fix" script from a forum. Both can make a broken server an unsafe one. Swap it for a maintained one instead. Every server in our directory shows how recently it was maintained and how it signs in, and how TrustedMCP scores servers explains the grade. Before installing a replacement, run the checks in is this MCP server safe?.

If you run an MCP server your team depends on and want it reviewed, or need one built properly, get in touch.

Frequently asked questions

Why is my MCP server not working?

Usually one of six things, in this order: the command doesn't start in the app, the server doesn't answer the handshake, tools/list is empty, it isn't signed in, it times out, or the tool itself returns an error. Run the command by hand first; most failures show up there.

What does MCP error -32000 mean?

In the official SDKs, -32000 means "Connection closed": the server went away before it answered. For a local server, the process usually exited because the command wasn't found, a key was missing, or it crashed. Read the server's stderr log for the real reason.

Why are my MCP tools not loading (0 tools)?

The server started but returned an empty tool list, most often because a required API key or setting is missing. Test it with the MCP Inspector's tools/list. If the Inspector shows tools and your app doesn't, it's the app: toggle the server off and on, start a new chat, and update the app.

Why does my MCP server keep disconnecting?

A local server that disconnects has usually crashed, so read its log. A remote one may be restarting, rate-limiting you, or down. Your computer sleeping can also drop the connection. If it happens to everyone at once, it's an outage.

Why is my MCP server not working in Claude Code?

Run claude mcp list or /mcp to see each server's status, then claude mcp get <name> for the error detail. Failed to connect means the command or URL is wrong; connected with no tools usually means a missing environment variable. Claude Code versions before v2.1.302 also showed tools fetch failed for some servers on the 2026-07-28 spec, so update first.

Where are the Claude Desktop MCP logs?

~/Library/Logs/Claude on macOS, %APPDATA%\Claude\logs on Windows and ~/.config/Claude/logs on Linux. mcp.log covers connections; mcp-server-<name>.log holds each server's own output.

Why does my MCP server work in the terminal but not in Claude Desktop?

The app starts the server in a different folder and with fewer environment variables than your terminal. Use absolute paths, put keys in the server's env block, and use the full path to npx or node if the app can't find it.

How do I test an MCP server without Claude?

Use the MCP Inspector. Its CLI runs one method and exits, for example --method tools/list, so you can see what the server returns without any app in the way. Our MCP Inspector guide has the commands.

Is it safe to keep using a server that keeps breaking?

A server that fails often is often unmaintained, and unmaintained servers don't get security fixes either. Check when it was last updated and whether it has open security reports before you rely on it.