### fantastic-computing-machine-io ###
[pull request](https-github.com-pimpn-droid-knot-XVOiBO-XVOiBO-B)
@phantomtech573-fantastic-computing-machine-README-md
pull release update from
@phantomtech573-fantastic-computing-machine-README.md
Fetch the complete documentation index https-modelcontextprotocol-io-llms-txt``` Use this file to discover all available pages before exploring further. ``
• A comprehensive guide to debugging •Model Context Protocol (MCP) integrations
• when developing MCP servers •integrating them with applications. • debugging tools and approaches available in the MCP ecosystem.
<Info>
This guide is for macOS. Guides for other platforms are coming soon.
</Info>
## Debugging tools overview
MCP provides several tools for debugging at different levels:
1. **MCP Inspector**
* Interactive debugging interface
* Direct server testing
* See the [Inspector guide](/docs/tools/inspector) for details
2. **Claude Desktop Developer Tools**
* Integration testing
* Log collection
* Chrome DevTools integration
3. **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:
1. Click the <img src="https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-plug-icon.svg?fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=54a3607debed10d16418e37a17288d22" style={{display: 'inline', margin: 0, height: '1.3em'}} data-og-width="32" width="32" data-og-height="32" height="32" data-path="images/claude-desktop-mcp-plug-icon.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-plug-icon.svg?w=280&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=09baf22cc2e6c073f10b227f30aad5cd 280w, https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-plug-icon.svg?w=560&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=58cda1b1044b529483adc75b2f9239f0 560w, https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-plug-icon.svg?w=840&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=ee8269c651c630de20069fd272930ac0 840w, https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-plug-icon.svg?w=1100&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=679d12146c6b954a7775c26f47daec9e 1100w, https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-plug-icon.svg?w=1650&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=2faae164af5faed3b21faae871a381f9 1650w, https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-plug-icon.svg?w=2500&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=c11cee0a2e57b283a364d31d8954c31e 2500w" /> icon to view:
* Connected servers
* Available prompts and resources
2. Click the "Search and tools" <img src="https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-slider.svg?fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=6968a0ba9822c5f41dfeb719bbb7548b" style={{display: 'inline', margin: 0, height: '1.3em'}} data-og-width="24" width="24" data-og-height="24" height="24" data-path="images/claude-desktop-mcp-slider.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-slider.svg?w=280&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=ed9957d9dc43c95976a8b40e414b932d 280w, https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-slider.svg?w=560&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=37ec89945a2d0a2f697c7013dc1982f7 560w, https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-slider.svg?w=840&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=b2d3e7bb033528b23755cb6baa68ba5d 840w, https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-slider.svg?w=1100&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=caa4d44e51ed46ccba9213093d8b2dc1 1100w, https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-slider.svg?w=1650&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=93ee7d62caea479b969cb4f6971f9fb6 1650w, https://mintcdn.com/mcp/C7bOrAKftvTohitd/images/claude-desktop-mcp-slider.svg?w=2500&fit=max&auto=format&n=C7bOrAKftvTohitd&q=85&s=b9a28be36fb4526992b18de4d5625047 2500w" /> icon to view:
* Tools made available to the model
### Viewing logs
Review detailed MCP logs from Claude Desktop:
```bash theme={null}
# 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
Access Chrome's developer tools inside Claude Desktop to investigate client-side errors:
- Create a
developer_settings.jsonfile withallowDevToolsset to true:
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
When using MCP servers with Claude Desktop:
- The working directory for servers launched via
claude_desktop_config.jsonmay be undefined (like/on macOS) since Claude Desktop could be started from anywhere - Always use absolute paths in your configuration and
.envfiles 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:
{
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/data"
]
}Instead of relative paths like ./data
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:
{
"myserver": {
"command": "mcp-server-myapp",
"env": {
"MYAPP_API_KEY": "some_key"
}
}
}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
When servers fail to connect:
- Check Claude Desktop logs
- Verify server process is running
- Test standalone with Inspector
- Verify protocol compatibility
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 Python theme={null} server.request_context.session.send_log_message( level="info", data="Server started successfully", ) ```server.sendLoggingMessage({
level: "info",
data: "Server started successfully",
});Important events to log:
- Initialization steps
- Resource access
- Tool execution
- Error conditions
- Performance metrics
In client applications:
- Enable debug logging
- Monitor network traffic
- Track message exchanges
- Record error states
-
Initial Development
- Use Inspector for basic testing
- Implement core functionality
- Add logging points
-
Integration Testing
- Test in Claude Desktop
- Monitor logs
- Check error handling
To test changes efficiently:
- Configuration changes: Restart Claude Desktop
- Server code changes: Use Command-R to reload
- Quick iteration: Use Inspector during development
-
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
When debugging:
-
Sensitive Data
- Sanitize logs
- Protect credentials
- Mask personal information
-
Access Control
- Verify permissions
- Check authentication
- Monitor access patterns
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
