diff --git a/docs/tools/debugging.mdx b/docs/tools/debugging.mdx index 126630b..b0f6f83 100644 --- a/docs/tools/debugging.mdx +++ b/docs/tools/debugging.mdx @@ -1,10 +1,14 @@ --- -title: Debugging MCP servers -description: A comprehensive guide to debugging Model Context Protocol (MCP) servers and integrations +title: Debugging +description: 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: @@ -12,9 +16,9 @@ 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 + - See the [Inspector guide](/docs/tools/inspector) for details -2. **Claude.app Developer Tools** +2. **Claude Desktop Developer Tools** - Integration testing - Log collection - Chrome DevTools integration @@ -24,7 +28,7 @@ MCP provides several tools for debugging at different levels: - Error tracking - Performance monitoring -## Debugging in Claude.app +## Debugging in Claude Desktop ### Checking server status @@ -32,20 +36,18 @@ The Claude.app interface provides basic server status information: 1. Click the 🔌 icon to view: - Connected servers - - Available prompts - - Accessible resources - - Supported tools + - Available prompts and resources -### Enabling logging +2. Click the 🔨 icon to view: + - Tools made available to the model -Get detailed logs from Claude.app: +### Viewing logs + +Review detailed MCP logs from Claude Desktop: ```bash -# Launch with logging enabled -open /Applications/Claude.app --stdout ~/Claude.log --stderr ~/Claude.log - # Follow logs in real-time -tail -n 100 -f ~/Claude.log +tail -n 20 -f ~/Logs/Claude/mcp*.log ``` The logs capture: @@ -56,7 +58,7 @@ The logs capture: ### Using Chrome DevTools -Access Chrome's developer tools for deeper inspection: +Access Chrome's developer tools inside Claude Desktop to investigate client-side errors: 1. Enable DevTools: ```bash @@ -70,9 +72,9 @@ 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: -- WebSocket connections -- Server-sent events - Message payloads - Connection timing @@ -80,15 +82,16 @@ Use the Network panel to inspect: ### Environment variables -MCP servers don't inherit environment variables automatically. Configure them in `claude_desktop_config.json`: +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`: ```json { "myserver": { "command": "mcp-server-myapp", "env": { - "HOME": "/Users/username", - "PATH": "/usr/local/bin:/usr/bin:/bin" + "MYAPP_API_KEY": "some_key", } } } @@ -117,23 +120,41 @@ Common initialization problems: When servers fail to connect: -1. Check Claude.app logs +1. Check Claude Desktop logs 2. Verify server process is running -3. Test standalone with Inspector -4. Check network connectivity -5. Verify protocol compatibility +3. Test standalone with [Inspector](/docs/tools/inspector) +4. Verify protocol compatibility ## Implementing logging ### Server-side logging -Implement custom logging in your server: +When building a server that uses the local stdio [transport](/docs/concepts/transports), all messages logged to stderr (standard error) will be captured by the client (e.g., Claude Desktop) automatically. -```typescript -server.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => { - console.log(`[${notification.params.level}] ${notification.params.data}`); -}); -``` + + Local MCP servers should not log messages to stdout (standard out), as this will interfere with protocol operation. + + +For all [transports](/docs/concepts/transports), you can also provide logging to the client by sending a log message notification: + + + + ```python + server.request_context.session.send_log_message( + level="info", + data="Server started successfully", + ) + ``` + + + ```typescript + server.sendLoggingMessage({ + level: "info", + data: "Server started successfully", + }); + ``` + + Important events to log: - Initialization steps @@ -156,27 +177,22 @@ In client applications: ### Development cycle 1. Initial Development - - Use Inspector for basic testing + - Use [Inspector](/docs/tools/inspector) for basic testing - Implement core functionality - Add logging points 2. Integration Testing - - Test in Claude.app + - Test in Claude Desktop - Monitor logs - Check error handling -3. Production Deployment - - Verify logging - - Monitor performance - - Track errors - ### Testing changes To test changes efficiently: -- **Configuration changes**: Restart Claude.app +- **Configuration changes**: Restart Claude Desktop - **Server code changes**: Use Command-R to reload -- **Quick iteration**: Use Inspector during development +- **Quick iteration**: Use [Inspector](/docs/tools/inspector) during development ## Best practices @@ -220,14 +236,13 @@ When encountering issues: 1. **First Steps** - Check server logs - - Test with Inspector + - Test with [Inspector](/docs/tools/inspector) - Review configuration - Verify environment 2. **Support Channels** - - #mcp-sig channel - GitHub issues - - MCP Asana project + - GitHub discussions 3. **Providing Information** - Log excerpts @@ -239,4 +254,4 @@ When encountering issues: - Learn to use the [MCP Inspector](/docs/tools/inspector) - Review [Protocol Overview](/api-reference/protocol-overview) -- Study [Error Handling](/api-reference/error-handling) \ No newline at end of file +- Study [Error Handling](/api-reference/error-handling) diff --git a/docs/tools/inspector.mdx b/docs/tools/inspector.mdx index cc86d2c..ecd2392 100644 --- a/docs/tools/inspector.mdx +++ b/docs/tools/inspector.mdx @@ -1,9 +1,9 @@ --- -title: MCP Inspector +title: Inspector description: In-depth guide to using the MCP Inspector for testing and debugging Model Context Protocol servers --- -The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive developer tool for testing and debugging MCP servers. While the [Debugging Guide](docs/tools/debugging) covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities. +The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive developer tool for testing and debugging MCP servers. While the [Debugging Guide](/docs/tools/debugging) covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities. ## Getting started @@ -20,111 +20,35 @@ Pass arguments to your server after the path: npx @modelcontextprotocol/inspector path/to/server.js arg1 arg2 ``` -## Interface overview +## Feature overview -The Inspector provides several key panels for interacting with your MCP server: +The Inspector provides several features for interacting with your MCP server: -### Server info panel -- Displays server name and version -- Shows negotiated protocol version -- Lists supported capabilities -- Indicates connection status +### Server connection pane +- Allows selecting the [transport](/docs/concepts/transports) for connecting to the server +- For local servers, supports customizing the command-line arguments and environment -### Resources browser +### Resources tab - Lists all available resources - Shows resource metadata (MIME types, descriptions) - Allows resource content inspection - Supports subscription testing -### Prompts panel +### Prompts tab - Displays available prompt templates - Shows prompt arguments and descriptions - Enables prompt testing with custom arguments - Previews generated messages -### Tools panel +### Tools tab - Lists available tools - Shows tool schemas and descriptions -- Provides input validation +- Enables tool testing with custom inputs - Displays tool execution results -## Testing features - -### Resource testing -```typescript -// Example resource URI to test -resource://myapp/data/123 -``` - -1. View resource metadata -2. Inspect content representations -3. Test subscription updates -4. Monitor resource changes - -### Prompt testing - -Test prompts with different arguments: -```json -{ - "temperature": 0.7, - "style": "concise" -} -``` - -1. Validate argument constraints -2. Preview generated messages -3. Test error conditions -4. Check template rendering - -### Tool testing - -Test tool execution with various inputs: -```json -{ - "query": "SELECT * FROM users", - "limit": 10 -} -``` - -1. Validate input schemas -2. Test error handling -3. Monitor execution progress -4. Inspect tool results - -## Advanced usage - -### Message inspector - -The Message inspector panel shows all communication between the client and server: - -1. Request/response pairs -2. Notifications -3. Progress updates -4. Error messages - -This helps debug: -- Protocol conformance -- Message formatting -- Error conditions -- State transitions - -### Subscription testing - -Test resource subscriptions: - -1. Subscribe to resources -2. Monitor update notifications -3. Test unsubscribe behavior -4. Verify update patterns - -### Capability testing - -Verify server capabilities: - -1. Check supported features -2. Test capability negotiation -3. Verify feature availability -4. Monitor initialization flow +### Notifications pane +- Presents all logs recorded from the server +- Shows notifications received from the server ## Best practices @@ -137,52 +61,16 @@ Verify server capabilities: 2. Iterative testing - Make server changes - - Restart Inspector + - Rebuild the server + - Reconnect the Inspector - Test affected features - Monitor messages -3. Error testing - - Test invalid inputs - - Check error responses - - Verify error handling - - Test recovery flows - -### Tips and tricks - -1. Keep Inspector Running - - Monitor changes in real-time - - Quick iteration cycle - - Immediate feedback - -2. Use Message Filtering - - Filter by message type - - Focus on specific features - - Debug targeted behaviors - -3. Test Edge Cases - - Invalid resource URIs - - Malformed tool inputs +3. Test edge cases + - Invalid inputs - Missing prompt arguments - Concurrent operations - -## Common patterns - -### Development loop - -1. Start server development -2. Launch Inspector -3. Implement feature -4. Test in Inspector -5. Refine implementation -6. Repeat - -### Integration testing - -1. Test basic functionality -2. Verify error handling -3. Check performance -4. Validate protocols -5. Test user flows + - Verify error handling and error responses ## Next steps @@ -218,4 +106,4 @@ Verify server capabilities: > Review message specifications - \ No newline at end of file +