How to Fix the Claude MCP Server Failed Error

The message “MCP server failed” is a symptom, not one defined error. The fastest path is to identify whether Claude is starting a local process or connecting to a remote MCP connector, validate the local configuration and launch command, fully quit and reopen Claude Desktop, then inspect the MCP logs. Check credentials, file permissions, and organization policy if the server still fails.

This guide focuses on local MCP servers and desktop extensions in Claude Desktop. Claude Code, remote connectors, and server-specific failures use different setup and diagnostics.

1. Identify what kind of MCP connection failed

Connection	Where it runs	First checks
Local MCP server or desktop extension	Your computer, launched by Claude Desktop	JSON syntax, `command`, `args`, absolute paths, permissions, restart, local logs
Remote MCP connector	A remote service reached over the network	Connector setup, authentication, network access, service status, remote-connector logs
Claude Code integration	Claude Code’s own runtime and configuration	Claude Code documentation and its process output

Anthropic documents local desktop extensions and remote custom connectors as separate setup paths. Do not apply a local claude_desktop_config.json fix to a remote connector without checking which connection you configured. See the Anthropic Help Center and the Model Context Protocol server guide.

2. Fix a local Claude Desktop server

Step 1: Locate the configuration file

The standard Claude Desktop configuration locations are:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %AppData%\\Claude\\claude_desktop_config.json

Open the file with a JSON-aware editor. A local server belongs under an mcpServers object. The exact executable and arguments depend on the server and operating system:

{
  "mcpServers": {
    "your-server-name": {
      "command": "/absolute/path/to/runtime-or-executable",
      "args": ["/absolute/path/to/server-file", "--optional-argument"]
    }
  }
}

This is a configuration shape, not a universal command. Replace the placeholders with the command that actually builds and runs your server.

Step 2: Validate JSON and paths

Check commas, braces, quotation marks, and escaping.
Use absolute paths for the executable and every server file.
On Windows, use escaped backslashes such as C:\\Users\\you\\server.js or use forward slashes.
Confirm the executable exists and is runnable by the same user account that launches Claude Desktop.
Confirm every file in args exists and that the working directory, if your server requires one, is accessible.

Run the configured command outside Claude Desktop using the same arguments. The correct command varies by runtime, so use your server’s documented build and start command. If it fails in a terminal, Claude will fail to start it too.

Step 3: Keep stdio output clean

For a stdio-based server, standard output carries JSON-RPC protocol messages. Diagnostic text on stdout can corrupt the protocol and make the server appear dead. Send diagnostics to stderr or a log file. The MCP guide states: For STDIO-based servers: Never use println(), as it writes to standard output (stdout) by default.

Step 4: Fully quit and restart Claude Desktop

Saving the file and closing the window may leave Claude Desktop running. Fully quit it, then reopen it:

macOS: use Cmd+Q or the Claude menu.
Windows: quit Claude from the system tray.
Linux: quit from the tray or terminate the running app from a terminal.

Restart after every configuration change. Tools may not appear until the application has been fully restarted.

Step 5: Check credentials, permissions, and extension settings

Complete every required field in the extension settings.
Recheck API keys, tokens, and other credentials; remove accidental whitespace.
Confirm the account running Claude can read the server files and execute the runtime.
Check operating-system security prompts or permissions that block the executable.
On a managed computer, ask an administrator whether enterprise policy disables desktop extensions or restricts their directory. Machine-level policy can override in-app allowlists and blocklists.

3. Read the logs instead of guessing

Claude Desktop exposes connection status and server logs in its Developer settings. Enable debug logging when an extension issue is not clear. The MCP build guide identifies these log directories:

macOS: ~/Library/Logs/Claude
Linux: ~/.config/Claude/logs/

Look for two files:

Log	What it tells you
`mcp.log`	General connection attempts, startup failures, and lifecycle events
`mcp-server-SERVERNAME.log`	That server’s stderr output and runtime-specific errors

Match the symptom to the evidence. A missing server usually points to configuration, paths, permissions, extension settings, or a restart. A visible server with unavailable tools points to required fields, credentials, startup output, or a server that did not finish building. A tool that appears but fails during calls requires the server log and the tool’s own error details.

4. Troubleshoot by symptom

“The MCP server is not showing up in Claude”

Confirm the entry is nested under mcpServers.
Validate JSON syntax.
Replace relative paths with absolute paths.
Run the command manually.
Fully quit and reopen Claude Desktop.
Check whether policy blocks the extension.

“The extension is installed, but its tools are unavailable”

Restart Claude Desktop completely, then inspect required configuration fields and credentials. Verify that every configured path exists and is readable. Check mcp.log and the named server log for startup errors.

“Tool calls fail silently”

Inspect the named server’s stderr log and confirm the server builds and runs successfully outside Claude. For stdio servers, remove all debug prints from stdout. A single startup message written to stdout can break JSON-RPC framing.

“Couldn’t reach the MCP server”

First determine whether the server is local or remote. For local servers, check the command, file paths, permissions, and process startup. For remote connectors, check connector authentication and network routing instead of editing local desktop configuration.

It worked before a configuration edit

Restore the last known-good JSON, save it, fully quit Claude Desktop, and reopen it. Then reapply one change at a time so the failing field is identifiable.

The logs show an access or security error

Verify filesystem ownership and execute/read permissions for the runtime, server file, and any required working directory. On managed devices, request an administrator review of extension policy.

5. A repeatable diagnostic checklist

☐ Identify local process versus remote connector.
☐ Confirm the correct Claude product: Desktop, Claude Code, or another MCP host.
☐ Validate JSON syntax.
☐ Confirm mcpServers, server name, command, and arguments.
☐ Use absolute paths and correctly escaped Windows paths.
☐ Run the command manually with the same arguments.
☐ Keep protocol output on stdout and diagnostics on stderr.
☐ Confirm credentials, required fields, and file permissions.
☐ Fully quit and relaunch Claude Desktop.
☐ Read Developer settings, mcp.log, and the named server log.
☐ Ask an administrator about enterprise policy when the device is managed.

6. Performance, reliability, and maintenance

Startup reliability depends on deterministic paths and a repeatable launch command. Pin the runtime location your server expects, keep its build step separate from Claude startup, and avoid writing progress output to stdout. After upgrades, confirm the command still resolves and review the first startup lines in the server log.

For intermittent failures, record the exact time, client (Claude Desktop or another host), connection type, server name, and the first relevant log error. This separates a process crash, an authentication failure, a permissions problem, and a remote network issue.

Or skip the browser setup

If your MCP workflow needs screenshots for an AI agent, ScreenshotNeo provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools. It also has a one-request HTTP API, so there is no browser process or local screenshot server to configure:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. The MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and start with 1,000 screenshots per month at no charge.

FAQ

Does “server failed” prove Claude is down?

No. The phrase does not identify a universal outage or version bug. Logs and the connection type are needed to diagnose the cause.

Do I need to reinstall Claude Desktop?

Usually not. Validate configuration, run the server manually, fully restart Claude, and inspect logs before reinstalling anything.

Why are absolute paths recommended?

Claude may launch the process with a different working directory than your terminal. Absolute paths remove that ambiguity.

Can I use local-server instructions for a remote MCP connector?

No. Remote connectors have a different setup and authentication path. Identify the connection type first.

Where should server debug messages go?

Use stderr or a file. Stdout is reserved for stdio MCP protocol messages.