modelcontextprotocol/docs
Watch
1
0
Fork
You've already forked docs
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #16 from modelcontextprotocol/justin/fixes-2

Browse source 
Update "Development Tools"
This commit is contained in:
Justin Spahr-Summers 2024-11-21 14:48:20 +00:00 • committed by GitHub
commit 0854b8e900
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 79 additions and 176 deletions
Download patch file Download diff file Expand all files Collapse all files

101
docs/tools/debugging.mdx
View file

@ -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.
<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:
@ -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}`);
});
```
<Warning>
Local MCP servers should not log messages to stdout (standard out), as this will interfere with protocol operation.
</Warning>
For all [transports](/docs/concepts/transports), you can also provide logging to the client by sending a log message notification:
<Tabs>
<Tab title="Python">
```python
server.request_context.session.send_log_message(
level="info",
data="Server started successfully",
)
```
</Tab>
<Tab title="TypeScript">
```typescript
server.sendLoggingMessage({
level: "info",
data: "Server started successfully",
});
```
</Tab>
</Tabs>
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)
- Study [Error Handling](/api-reference/error-handling)

152
docs/tools/inspector.mdx
View file

@ -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
</Card>
</CardGroup>
</CardGroup>