​

Debugging tools overview

1. MCP Inspector: interactive, transport-agnostic testing UI. Connect to stdio or Streamable HTTP servers, invoke tools, prompts, and resources, and watch the notification stream. This should be your first stop.
2. Server logging: structured logs to stderr (stdio transport) or via OpenTelemetry (all transports). Logging over the protocol (notifications/message) is deprecated as of protocol version 2026-07-28.
3. Client developer tools: most MCP clients expose logs and connection state. See Debugging in Claude Desktop below for one example, or consult your client’s documentation.

​

Implementing logging

​

Server-side logging

import logging

from mcp.server import MCPServer

logger = logging.getLogger(__name__)

mcp = MCPServer("reports")


@mcp.tool()
async def fetch_report(report_id: str) -> str:
    """Fetch a report by id."""
    logger.info("Fetching report %s", report_id)
    return f"Report {report_id} is ready."

await server.sendLoggingMessage({
  level: "info",
  data: "Server started successfully",
});

• Startup steps
• Resource access
• Tool execution
• Error conditions
• Performance metrics

​

Common issues

​

Working directory

• The working directory for servers launched via the client’s config may be undefined (like / on macOS) since the client could be started from anywhere
• Always use absolute paths in your configuration and .env files to ensure reliable operation
• For testing servers directly via command line, the working directory will be where you run the command

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/data"
      ]
    }
  }
}

​

Environment variables

{
  "mcpServers": {
    "myserver": {
      "command": "mcp-server-myapp",
      "env": {
        "MYAPP_API_KEY": "some_key"
      }
    }
  }
}

​

Server startup

1. Path Issues
   • Incorrect server executable path
   • Missing required files
   • Permission problems
   • Try using an absolute path for command
2. Configuration Errors
   • Invalid JSON syntax
   • Missing required fields
   • Type mismatches
3. Environment Problems
   • Missing environment variables
   • Incorrect variable values
   • Permission restrictions

​

Connection problems

1. Check client logs
2. Verify server process is running
3. Test standalone with Inspector
4. Verify protocol compatibility: call server/discover to see which protocol versions the server supports. An UnsupportedProtocolVersionError (-32022) lists the server’s supported versions in its data field
5. Check the per-request _meta fields: every request must carry io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities, and clients should also include io.modelcontextprotocol/clientInfo. A request missing either required field is rejected with error -32602 (Invalid params), the same code returned for many other malformed inputs. If the server needs a capability the request’s clientCapabilities did not declare, such as elicitation, it returns a MissingRequiredClientCapabilityError (-32021) naming the missing capabilities. Inspect the request’s _meta and the server/discover response to verify both sides declared what you expect

​

Debugging in Claude Desktop

​

Checking server status

​

Viewing logs

• macOS: ~/Library/Logs/Claude
• Windows: %APPDATA%\Claude\logs

tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

type "$env:AppData\Claude\logs\mcp*.log"

• Server connection events
• Configuration issues
• Runtime errors
• Message exchanges

​

Using Chrome DevTools

1. Create a developer_settings.json file with allowDevTools set to true:

echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json

'{"allowDevTools": true}' | Set-Content "$env:AppData\Claude\developer_settings.json"

2. Open DevTools: Command-Option-I (macOS) or Ctrl+Alt+I (Windows)

• Main content window
• App title bar window

• Message payloads
• Connection timing

​

Debugging workflow

​

Development cycle

1. Initial Development
   • Use Inspector for basic testing
   • Implement core functionality
   • Add logging points
2. Integration Testing
   • Test in your target MCP client
   • Monitor logs
   • Check error handling

​

Testing changes

• Configuration changes: Restart the MCP client
• Server code changes: Restart the client (for Claude Desktop, fully quit and reopen; closing the window is not enough)
• Quick iteration: Use Inspector during development

​

Best practices

​

Logging strategy

1. Structured Logging
   • Use consistent formats
   • Include context
   • Add timestamps
   • Track request IDs
2. Error Handling
   • Log stack traces
   • Include error context
   • Track error patterns
   • Monitor recovery
3. Performance Tracking
   • Log operation timing
   • Monitor resource usage
   • Track message sizes
   • Measure latency

​

Security considerations

1. Sensitive Data
   • Sanitize logs
   • Protect credentials
   • Mask personal information
2. Access Control
   • Verify permissions
   • Check authentication
   • Monitor access patterns

​

Getting help

1. First Steps
   • Check server logs
   • Test with Inspector
   • Review configuration
   • Verify environment
2. Support Channels
   • GitHub issues
   • GitHub discussions
3. Providing Information
   • Log excerpts
   • Configuration files
   • Steps to reproduce
   • Environment details

​

Next steps