How do I reset my MCP client configuration?

Delete the client's config file (for example claude_desktop_config.json) and restart the client; it will regenerate with defaults, and you can re-add servers one at a time.

Why does my server work locally but not in production?

The usual causes are a missing environment variable, a different Node.js version, a firewall rule, or a relative path that only resolved correctly on your machine. Check each one systematically rather than guessing.

How do I see the raw request and response for a failing tool call?

Run the server through the MCP Inspector and call the tool directly; it shows the exact JSON-RPC payload and the schema validation error, which is faster than reading server logs.

troubleshootingHowTo

MCP Troubleshooting: Common Issues and Fixes

Fixes for the MCP errors developers hit most: command-not-found, connection refused, auth failures, tool-not-found, and out-of-memory crashes.

Quick Answer / TL;DR

Most MCP issues trace back to three causes: an incorrect or relative command path in the client configuration, a missing environment variable, or a network or firewall restriction blocking the connection. Check those first before deeper debugging.

Key Takeaways

Always use absolute paths in claude_desktop_config.json and similar client configs.
Stdout must carry only JSON-RPC frames; send debug output to stderr instead.
The MCP Inspector is the fastest way to test a server interactively before wiring it into a client.

Connection issues

A 'command not found' error almost always means the command path in the client configuration is relative or wrong. Use an absolute path to the executable, confirm the file exists and is executable, and start the server manually from a terminal to surface the real error before blaming the client.

'Connection refused' means nothing is listening on the expected port. Confirm the process is actually running, check what is bound to the port, and verify firewall rules if the server is remote. A timeout usually means the server is slow to respond rather than unreachable; increase the client timeout and check server logs for a slow downstream call before assuming the network is at fault.

text

# Verify the executable and permissions
which node
ls -la /absolute/path/to/server/dist/index.js
chmod +x /absolute/path/to/server/dist/index.js

# Check what is listening on a port
lsof -i :3000

Authentication and tool errors

A 401 usually means a missing or malformed credential; print the environment variable (without logging it anywhere persistent) to confirm it is set and has no stray whitespace. A 403 means the caller authenticated fine but the role attached to them does not permit the requested method; check the RBAC mapping rather than the credential itself.

'Tool not found' is almost always a name mismatch: tool names are case-sensitive and must match exactly between the list-tools handler and the call-tool handler. 'Invalid input' means the arguments the client sent do not match the tool's declared schema; use the MCP Inspector to call the tool directly and see the exact validation failure.

bash

npx @modelcontextprotocol/inspector node server.js

Performance and memory issues

A server that feels slow is usually blocked on a downstream call, most often an unindexed database query. Profile the specific tool, add the missing index, and add connection pooling and a response cache before assuming the protocol itself is the bottleneck.

An out-of-memory crash usually means a tool is loading an entire result set into memory instead of streaming it. Raise the Node heap limit as a stopgap, but fix the root cause by streaming large datasets row by row instead of materializing them all at once.

bash

# Stopgap: raise the heap limit
node --max-old-space-size=4096 server.js

# Real fix: stream instead of loading everything
const stream = db.query("SELECT * FROM large_table").stream();
for await (const row of stream) {
  // process row by row
}