MCP Troubleshooting Guide

Having trouble with your MCP setup? Don’t worry - most MCP issues have simple solutions. This guide covers the most common problems and their fixes, plus tips to prevent issues from happening in the first place.

Quick Diagnostic Checklist

Before diving into specific solutions, run through this quick checklist for simple but common issues:

• Correct API credentials? - Check if keys/tokens are valid and not expired
• Proper permissions? - Ensure your API access includes necessary scopes
• Server running? - Verify MCP servers are active and responding
• Rate limits hit? - Make sure the APIs haven’t limited your requests

Most Common Issues and Solutions

1. “Connection Failed” or “Server Not Found”

Symptoms:

• Claude can’t connect to your MCP server
• Error messages about unreachable servers
• Timeout errors during connection attempts

Quick Fixes:

Check Server Status:

# Test if your MCP server is running
curl http://localhost:3000/health

# If using a specific MCP server (example with filesystem server)
mcp-server-filesystem --version

Verify Configuration:

// Check your Claude Desktop MCP configuration
{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["--path", "/your/directory/path"]
    }
  }
}

Restart Services:

1. Close Claude Desktop completely
2. Restart your MCP server
3. Reopen Claude Desktop
4. Test the connection

2. Authentication and Permission Errors

Symptoms:

• “Access denied” or “Unauthorized” errors
• “Invalid credentials” messages
• Partial functionality (some features work, others don’t)

Solutions:

Check API Credentials:

# Test API credentials directly
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.example.com/v1/test

# For Gmail MCP server
mcp-server-gmail auth verify

Update Expired Tokens:

# Re-authenticate with OAuth services
mcp-server-gmail auth refresh

# For other services, check their documentation

Verify Permissions:

• Ensure your API key has all required scopes
• Check that your account has necessary permissions
• Confirm API access is enabled for your application

3. Slow Performance or Timeouts

Symptoms:

• Long delays before responses
• Timeout errors during operations
• Claude seems “stuck” processing requests

Performance Fixes:

Optimize Request Frequency:

# Add rate limiting to prevent API overload
mcp-server-your-service --rate-limit 100

# Cache responses to reduce API calls
mcp-server-your-service --cache-timeout 300

Check System Resources:

# Monitor CPU and memory usage
top -p $(pgrep mcp-server)

# Check disk space
df -h /tmp

Reduce Data Load:

• Limit the amount of data requested at once
• Use filters to get only necessary information
• Implement pagination for large datasets

4. Data Inconsistencies or Errors

Symptoms:

• Wrong information returned by MCP
• Missing data that should be available
• Outdated information despite recent changes

Data Quality Fixes:

Clear Cache:

# Clear MCP server cache
rm -rf ~/.mcp-cache/*

# Restart with fresh cache
mcp-server-your-service --clear-cache

Verify Data Sources:

• Check that source systems have correct data
• Ensure API endpoints are returning expected results
• Validate data transformation rules

Update Refresh Intervals:

{
  "refreshInterval": "300s",  // Refresh every 5 minutes
  "cacheTimeout": "600s"     // Cache for 10 minutes
}

5. Installation and Setup Problems

Symptoms:

• MCP server won’t install
• Missing dependencies
• Command not found errors

Installation Fixes:

Check Node.js Version:

# Ensure you have Node.js 18+ installed
node --version

# Update if necessary
npm install -g npm@latest

Install Missing Dependencies:

# Reinstall MCP server with all dependencies
npm uninstall -g @modelcontextprotocol/server-yourservice
npm install -g @modelcontextprotocol/server-yourservice

# For specific servers
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-gitlab

Fix Path Issues:

# Add npm global bin to your PATH
echo 'export PATH=$PATH:$(npm config get prefix)/bin' >> ~/.bashrc
source ~/.bashrc

Advanced Troubleshooting

Enable Debug Logging

Most MCP servers support debug mode for detailed logging:

# Enable debug logging
DEBUG=* mcp-server-yourservice

# Or for specific components
DEBUG=mcp:auth,mcp:api mcp-server-yourservice

Test API Connections Manually

Before blaming MCP, test the underlying APIs directly:

# Test REST API
curl -v -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     https://api.service.com/v1/endpoint

# Test database connection
psql -h localhost -U username -d database -c "SELECT 1;"

Monitor Resource Usage

Keep an eye on system resources:

# Monitor MCP server processes
htop -p $(pgrep mcp-server)

# Check network connections
netstat -an | grep :3000

# Monitor API rate limits
tail -f /var/log/mcp-server.log | grep "rate limit"

Platform-Specific Issues

Windows Users

Common Issues:

• Path separator problems (use \\ instead of /)
• PowerShell execution policy restrictions
• Windows Defender blocking MCP servers

Solutions:

# Set execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Use Windows-style paths
"args": ["--path", "C:\\Users\\YourName\\Documents"]

# Add Windows Defender exception
Add-MpPreference -ExclusionPath "C:\Users\YourName\AppData\Roaming\npm"

macOS Users

Common Issues:

• Gatekeeper blocking unsigned applications
• Permission issues with system directories
• Homebrew vs npm package conflicts

Solutions:

# Allow unsigned applications (use with caution)
sudo spctl --master-disable

# Fix npm permissions
sudo chown -R $(whoami) $(npm config get prefix)

# Use Homebrew-managed Node.js
brew install node

Linux Users

Common Issues:

• Package manager conflicts
• SELinux restrictions
• Firewall blocking connections

Solutions:

# Install via package manager
sudo apt-get update && sudo apt-get install nodejs npm

# Check SELinux status
sestatus

# Open firewall ports
sudo ufw allow 3000

Performance Optimization Tips

1. Optimize Cache Settings

{
  "cache": {
    "enabled": true,
    "ttl": 300,           // 5 minutes
    "maxSize": "100MB",
    "strategy": "lru"     // Least Recently Used
  }
}

2. Configure Connection Pooling

{
  "database": {
    "poolSize": 10,
    "maxRetries": 3,
    "retryDelay": 1000
  }
}

3. Implement Smart Rate Limiting

{
  "rateLimit": {
    "enabled": true,
    "requestsPerMinute": 60,
    "burstLimit": 10
  }
}

Monitoring and Maintenance

Set Up Health Checks

Create a simple monitoring script:

#!/bin/bash
# health-check.sh

# Check if MCP server is responding
if curl -f http://localhost:3000/health > /dev/null 2>&1; then
    echo "MCP server is healthy"
else
    echo "MCP server is down - restarting..."
    systemctl restart mcp-server
fi

Log Rotation

Prevent log files from filling up disk space:

# Setup logrotate for MCP logs
sudo cat > /etc/logrotate.d/mcp-server << EOF
/var/log/mcp-server.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
}
EOF

Regular Maintenance Tasks

Weekly maintenance checklist:

• Check log files for errors
• Verify API credentials haven’t expired
• Test critical MCP connections
• Review performance metrics
• Update MCP servers if needed

When to Get Help

Contact support or community forums if you encounter:

• Security vulnerabilities in MCP servers
• Data corruption or loss issues
• Persistent performance problems after optimization
• Integration conflicts with other software
• Business-critical failures that affect operations

Prevention Best Practices

1. Environment Management

# Use environment variables for configuration
export MCP_API_KEY="your-secret-key"
export MCP_LOG_LEVEL="info"
export MCP_CACHE_DIR="/tmp/mcp-cache"

2. Version Control

Keep track of your MCP configurations:

# Initialize git repo for configs
cd ~/.config/mcp
git init
git add .
git commit -m "Initial MCP configuration"

3. Backup Critical Data

# Backup MCP configurations
tar -czf mcp-backup-$(date +%Y%m%d).tar.gz ~/.config/mcp

# Backup authentication tokens
cp ~/.mcp-auth/tokens.json ~/.mcp-auth/tokens.backup.json

4. Testing Strategy

Test changes in a safe environment:

# Use development configuration
export MCP_ENV=development
mcp-server-yourservice --config development.json

Remember: Most MCP issues are configuration-related and can be solved by carefully checking your setup against the documentation. When in doubt, start with the simplest solution first!

Need more help? Join our Community Support Forum or check out our Advanced Configuration Guide.