104 lines
2.0 KiB
Markdown
104 lines
2.0 KiB
Markdown
# MCP Server Troubleshooting
|
|
|
|
## Error Handling Patterns
|
|
|
|
### Validation Errors
|
|
|
|
```typescript
|
|
if (!isValid(input)) {
|
|
throw new Error("Invalid input: expected format X, got Y");
|
|
}
|
|
```
|
|
|
|
### API Errors
|
|
|
|
```typescript
|
|
try {
|
|
const result = await externalAPI.call();
|
|
return result;
|
|
} catch (error) {
|
|
console.error("API error:", error);
|
|
return {
|
|
content: [{
|
|
type: "text",
|
|
text: `Error: ${error.message}. Please try again.`
|
|
}]
|
|
};
|
|
}
|
|
```
|
|
|
|
### Resource Not Found
|
|
|
|
```typescript
|
|
if (!resource) {
|
|
throw new Error(`Resource not found: ${uri}`);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Common Issues
|
|
|
|
| Issue | Cause | Solution |
|
|
|-------|-------|----------|
|
|
| Server not detected | Invalid path | Use absolute path, verify file exists |
|
|
| Tools don't appear | Build not run | Run `npm run build` |
|
|
| "Server error" | stdout logging | Remove console.log, use console.error |
|
|
| Connection timeout | Server crash | Check mcp-server-NAME.log for errors |
|
|
| Invalid config | JSON syntax | Validate JSON, check quotes/commas |
|
|
|
|
---
|
|
|
|
## Quick Reference Commands
|
|
|
|
### Check Claude Desktop Logs
|
|
|
|
```bash
|
|
tail -f ~/Library/Logs/Claude/mcp.log
|
|
tail -f ~/Library/Logs/Claude/mcp-server-[name].log
|
|
```
|
|
|
|
### Validate Config JSON
|
|
|
|
```bash
|
|
python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
|
```
|
|
|
|
### Test with MCP Inspector
|
|
|
|
```bash
|
|
npx @modelcontextprotocol/inspector [command] [args]
|
|
```
|
|
|
|
### Restart Claude Desktop
|
|
|
|
```bash
|
|
# macOS
|
|
osascript -e 'quit app "Claude"'
|
|
open -a Claude
|
|
```
|
|
|
|
---
|
|
|
|
## Transport-Specific Issues
|
|
|
|
### STDIO Transport
|
|
|
|
**Problem**: Server crashes with no error
|
|
**Cause**: Using console.log() which corrupts JSON-RPC
|
|
**Solution**: Use console.error() only
|
|
|
|
**Problem**: Server not responding
|
|
**Cause**: Blocking synchronous operation
|
|
**Solution**: Use async/await for all I/O
|
|
|
|
### HTTP Transport
|
|
|
|
**Problem**: Connection refused
|
|
**Cause**: Wrong port or server not running
|
|
**Solution**: Check PORT env var, verify server started
|
|
|
|
**Problem**: Authentication errors
|
|
**Cause**: Missing or invalid credentials
|
|
**Solution**: Configure auth headers/tokens
|