How to Debug MCP Server Issues

MCP server debugging is the process of diagnosing and fixing issues with Model Context Protocol servers, including connection failures, tool execution errors, and transport problems. Connection timeouts and transport mismatches are the most common MCP server issues developers face. The Model Context Protocol connects AI assistants (like Claude Desktop, Cursor, or custom applications) to external tools and data sources through MCP servers. When these servers fail to start, can't connect, or produce unexpected errors, debugging becomes necessary. Common categories of MCP server issues include:

• Connection errors: Server won't start or host can't reach it
• Protocol errors: Malformed JSON-RPC messages or version mismatches
• Tool execution failures: Tools defined but fail when invoked
• Transport problems: stdio, SSE, or Streamable HTTP misconfiguration
• Parsing errors: Invalid JSON output mixed with logs

To debug MCP servers, you need to understand the architecture, read logs correctly, and use the right tools to isolate problems.

Most MCP server problems fall into predictable patterns. Recognizing these patterns helps identify and fix issues faster.

Connection Refused (ECONNREFUSED) means the server process is not running, the transport path is wrong in your config, or there's a port conflict. Verify the server binary exists, the path is absolute (not relative), and no other process is using the same port.

Server Disconnected errors indicate the server crashed after starting, the transport configuration mismatches between client and server, or the server is writing logs to stdout instead of stderr. Check server logs for crash traces and confirm both sides use the same transport type.

Parsing Errors (Unexpected token) happen when debug output gets mixed with JSON-RPC messages on stdout. MCP servers must only write JSON-RPC to stdout. All logs, debug statements, and error messages must go to stderr.

Tool Not Found errors occur when the client requests a tool the server doesn't expose, or the tool list hasn't been refreshed after server changes. Restart both client and server, and verify tool definitions match.

Timeout Errors mean the server is taking too long to respond, network latency is high (for HTTP/SSE transports), or the server is blocked on a long-running operation without streaming progress.

The MCP Inspector is the official debugging tool from the Model Context Protocol team. It provides a browser-based interface for testing and debugging MCP servers with JSON tool calls and real-time logs. The Inspector consists of two components:

• MCP Inspector Client (MCPI): A React-based web UI for interactive testing
• MCP Proxy (MCPP): A Node.js server that bridges the UI to MCP servers via stdio, SSE, or Streamable HTTP

Running the Inspector:

npx @modelcontextprotocol/inspector <mcp-server-command>

Replace <mcp-server-command> with your server's startup command and arguments. The Inspector starts at http://localhost:6274.

Key Features:

Tools Panel: Lists all tools exposed by your server. Click any tool to see its schema, test it with sample inputs, and view responses.

Resources Panel: Browse static context provided by the server (file contents, database schemas, configuration data) without requiring tool calls.

Prompts Panel: Test server-provided prompts if your server implements the prompts capability.

Log Panel: Displays all messages exchanged between the Inspector and your server in real-time. This shows requests, responses, notifications, and errors. The log panel helps you see exactly what JSON-RPC messages are being sent, what the server responds with, and where failures occur in the protocol handshake.

Testing Tools: Click a tool in the Tools panel to open a test interface. Fill in parameters using the schema, invoke the tool, and see the raw response. This isolates tool logic from client integration issues.

Good logging is essential for MCP server debugging. Without visibility into what's happening, you're troubleshooting blind.

Important: MCP servers must only write JSON-RPC messages to stdout. All logs and debugging output must go to stderr.

Log Location by Host:

• Claude Desktop: Logs are at ~/Library/Logs/Claude/mcp-server-SERVERNAME.log (macOS) or %APPDATA%\Claude\logs\mcp-server-SERVERNAME.log (Windows)
• Custom Applications: Configure logging to files or stderr streams based on your runtime

Logging Strategy:

Use structured logs directed to stderr. Include context in every log entry: server name, method being called, request ID, and timestamps. This makes it easier to trace requests through your server logic. ```python

Good logging (Python example)

import sys import logging

logging.basicConfig( stream=sys.stderr, level=logging.DEBUG, format='%(asctime)s [%(name)s] %(levelname)s: %(message)s' )

logger = logging.getLogger('my-mcp-server') logger.info(f"Processing tool call: {tool_name}")

**What to Log:**

- Server startup and shutdown events
- Incoming tool requests with parameters
- Tool execution results or errors
- Resource access attempts
- Transport connection/disconnection events

Tail server and host logs simultaneously during testing. This reveals timing issues, where the client sends a request but the server never receives it, or vice versa.

Give Your AI Agents Persistent Storage

Fast.io provides 251 MCP tools for file operations, built-in RAG, and a free tier with 50GB storage. Build AI agents that store files persistently, transfer ownership to humans, and collaborate across workspaces.

Explore Fast.io MCP Server

Connection errors like ECONNREFUSED and disconnected messages are the most frustrating because they're binary (it works or it doesn't), with little diagnostic information.

For stdio Transport:

Verify the server binary path in your host config is absolute, not relative. Relative paths fail when the host's working directory isn't what you expect. ```json { "mcpServers": { "my-server": { "command": "/absolute/path/to/server", "args": ["--config", "config.json"] } } }

Confirm the server process starts. Run the command manually in a terminal. If it crashes immediately, you'll see error output. If it waits for stdin, it's configured correctly. Check that the server executable has execute permissions (`chmod +x server` on Unix).

**For SSE/HTTP Transports:**

Verify the server is listening on the expected host and port. Use `curl` or `netcat` to test connectivity before involving the MCP client. ```bash
curl http://localhost:3000/sse

If you get "Connection refused", the server isn't running or is bound to a different port. If you get a response, the network path is working. Confirm no firewall or port conflicts (EADDRINUSE). Check if another process is using the port with lsof -i :3000 (Unix) or netstat -ano | findstr :3000 (Windows).

NVM and Node Version Issues:

If your MCP server is a Node.js script installed via nvm, Claude Desktop or other hosts may not find node in the PATH. The host's environment doesn't inherit nvm's shell configuration. Solution: Use absolute paths to the Node binary or invoke the server through a shell wrapper that sources nvm. json { "command": "/Users/username/.nvm/versions/node/v20.0.0/bin/node", "args": ["/path/to/server.js"] }

Protocol-level errors occur when there are issues with the MCP communication itself: malformed JSON-RPC messages, version mismatches, or connection failures between the client and server.

Unexpected Token Errors:

This indicates invalid JSON is being sent. The most common cause is mixing logs or debug output with JSON-RPC on stdout. Solution: Redirect all logging to stderr. Never use console.log() in Node.js servers, print() in Python servers, or fmt.Println() in Go servers for debugging. Use proper logging libraries configured to write to stderr.

Method Not Found (-32601):

The client requested a tool or capability the server doesn't recognize. This happens when:

• The server definition changed but the client cached the old tool list
• Typos in tool names
• The server doesn't implement the requested capability

Solution: Restart both client and server to clear caches. Verify tool names match exactly between server implementation and client requests.

Invalid Params (-32602):

The client sent parameters that don't match the tool's input schema. Common causes include missing required fields, wrong types (string instead of number), or extra fields not in the schema. Solution: Compare the error message's params field against your tool schema. Use the MCP Inspector to test tool calls with known-good inputs.

The MCP Inspector provides a GUI, but CLI testing is faster for automated tests and CI/CD pipelines. MCP uses JSON-RPC 2.0 over stdio or SSE transport. For stdio transport, you can test by piping JSON messages to your server's stdin and reading responses from stdout.

Basic stdio Test:

echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | ./server

The server should respond with an initialize response containing its capabilities.

Using jq for Structured Testing:

This guide demonstrates inspecting MCP servers using CLI tools and jq for JSON parsing. You can script complete request/response flows and verify outputs.

Automated Testing Strategy:

1. Send initialize request and verify response structure
2. Request tool list with tools/list and confirm expected tools appear
3. Invoke each tool with valid inputs and check for errors
4. Send invalid inputs and verify error responses

Automated tests catch regressions when you modify server code. Run them in CI to prevent broken servers from deploying.

When standard debugging doesn't reveal the issue, these advanced techniques help.

Proxy Debugging:

Place a logging proxy between your client and server to capture all traffic. This reveals exactly what messages are being exchanged, even when neither client nor server logs them properly. Tools like mitmproxy or custom Node.js proxies can intercept stdio or HTTP transports and log every byte.

Diff Server Output:

Compare your server's JSON output against a known-working server. Character-level diffs reveal subtle issues like extra whitespace, incorrect line endings, or encoding problems.

Version Pinning:

MCP is evolving rapidly. If your server worked previously but stopped, check if the client updated its MCP version. Pin SDK versions in your dependencies to avoid breaking changes.

Test with Multiple Clients:

If your server fails with Claude Desktop but works with the MCP Inspector, the issue is likely client-specific configuration, not your server logic. Test against multiple MCP clients (Claude Desktop, Cursor, custom apps) to isolate client vs server issues.

Instrument Tool Code:

Add detailed logging inside your tool implementations. When a tool fails, log the exact inputs received, each step of processing, and the final output before serialization. This isolates logic bugs from protocol bugs.

If you're building MCP servers for AI agents that need persistent file storage, Fast.io provides MCP-native storage with 251 MCP tools via Streamable HTTP and SSE transport.

Common File Storage Debugging Scenarios:

Agent Can't Access Files: Verify the agent has the right workspace permissions. Fast.io uses role-based access control. Agents need at least viewer role to read files, contributor to upload.

MCP Tool Returns 404: Check that the file ID or path is correct. Fast.io's MCP server uses workspace-scoped paths. A file in workspace A isn't accessible via workspace B's path.

Upload Fails: Fast.io's free agent tier supports files up to 1GB with chunked uploads. Ensure your MCP client is using the chunked upload tools for large files, not the basic upload.

RAG Returns No Results: Verify Intelligence Mode is enabled on the workspace. Intelligence Mode must be toggled on for RAG indexing to happen. Check the workspace settings via the MCP tools or dashboard.

Debugging MCP Storage with Fast.io:

Fast.io's MCP server includes detailed error responses with error objects containing diagnostic information. Enable MCP client logging to capture these errors. Test file operations using the MCP Inspector pointed at Fast.io's MCP endpoint. This isolates network issues from application logic. For human-agent collaboration workflows, verify ownership transfer worked correctly. Agents build data rooms and workspaces, then transfer ownership to humans while retaining admin access. Check the organization member list to confirm roles.