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 “Search and tools”
icon to view:
- Tools made available to the model
Viewing logs
Review detailed MCP logs from Claude Desktop:- 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 withallowDevTools
set to true:
- Open DevTools:
Command-Option-Shift-i
- Main content window
- App title bar window
- 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
claude_desktop_config.json
, use:
./data
Environment variables
MCP servers inherit only a subset of environment variables automatically, likeUSER
, HOME
, and PATH
.
To override the default variables or provide your own, you can specify an env
key in claude_desktop_config.json
:
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.
- 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