Debugging
A comprehensive guide to debugging Model Context Protocol (MCP) integrations

Effective debugging is essential when developing MCP servers or integrating them with applications. This guide covers the debugging tools and approaches available in the MCP ecosystem.

This guide is for macOS. Guides for other platforms are coming soon.

​
Debugging tools overview
MCP provides several tools for debugging at different levels:

MCP Inspector

Interactive debugging interface
Direct server testing
See the Inspector guide for details
Claude Desktop Developer Tools

Integration testing
Log collection
Chrome DevTools integration
Server Logging

Custom logging implementations
Error tracking
Performance monitoring
​
Debugging in Claude Desktop
​
Checking server status
The Claude.app interface provides basic server status information:

Click the  icon to view:

Connected servers
Available prompts and resources
Click the  icon to view:

Tools made available to the model
​
Viewing logs
Review detailed MCP logs from Claude Desktop:


Copy
# Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
The logs capture:

Server connection events
Configuration issues
Runtime errors
Message exchanges
​
Using Chrome DevTools
Access Chrome’s developer tools inside Claude Desktop to investigate client-side errors:

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

Copy
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
Open DevTools: Command-Option-Shift-i
Note: You’ll see two DevTools windows:

Main content window
App title bar window
Use the Console panel to inspect client-side errors.

Use the Network panel to inspect:

Message payloads
Connection timing
​
Common issues
​
Working directory
When using MCP servers with Claude Desktop:

The working directory for servers launched via claude_desktop_config.json may be undefined (like / on macOS) since Claude Desktop 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
For example in claude_desktop_config.json, use:


Copy
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}
Instead of relative paths like ./data

​
Environment variables
MCP servers inherit only a subset of environment variables automatically, like USER, HOME, and PATH.

To override the default variables or provide your own, you can specify an env key in claude_desktop_config.json:


Copy
{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}
​
Server initialization
Common initialization problems:

Path Issues

Incorrect server executable path
Missing required files
Permission problems
Try using an absolute path for command
Configuration Errors

Invalid JSON syntax
Missing required fields
Type mismatches
Environment Problems

Missing environment variables
Incorrect variable values
Permission restrictions
​
Connection problems
When servers fail to connect:

Check Claude Desktop logs
Verify server process is running
Test standalone with Inspector
Verify protocol compatibility
​
Implementing logging
​
Server-side logging
When building a server that uses the local stdio transport, all messages logged to stderr (standard error) will be captured by the host application (e.g., Claude Desktop) automatically.

Local MCP servers should not log messages to stdout (standard out), as this will interfere with protocol operation.

For all transports, you can also provide logging to the client by sending a log message notification:

Python
TypeScript

Copy
server.request_context.session.send_log_message(
  level="info",
  data="Server started successfully",
)
Important events to log:

Initialization steps
Resource access
Tool execution
Error conditions
Performance metrics
​
Client-side logging
In client applications:

Enable debug logging
Monitor network traffic
Track message exchanges
Record error states
​
Debugging workflow
​
Development cycle
Initial Development

Use Inspector for basic testing
Implement core functionality
Add logging points
Integration Testing

Test in Claude Desktop
Monitor logs
Check error handling
​
Testing changes
To test changes efficiently:

Configuration changes: Restart Claude Desktop
Server code changes: Use Command-R to reload
Quick iteration: Use Inspector during development
​
Best practices
​
Logging strategy
Structured Logging

Use consistent formats
Include context
Add timestamps
Track request IDs
Error Handling

Log stack traces
Include error context
Track error patterns
Monitor recovery
Performance Tracking

Log operation timing
Monitor resource usage
Track message sizes
Measure latency
​
Security considerations
When debugging:

Sensitive Data

Sanitize logs
Protect credentials
Mask personal information
Access Control

Verify permissions
Check authentication
Monitor access patterns
​
Getting help
When encountering issues:

First Steps

Check server logs
Test with Inspector
Review configuration
Verify environment
Support Channels

GitHub issues
GitHub discussions
Providing Information

Log excerpts
Configuration files
Steps to reproduce
Environment details
​
Next steps
