Troubleshooting Guide

Common issues and solutions for Model Context Protocol servers in enterprise environments.

Connection Issues

Resolve connectivity problems with enterprise systems

🔗 Database Connection Failures

Symptoms: Cannot connect to Oracle, Snowflake, or Postgres databases

Common Causes & Solutions:

  • Network connectivity: Verify VPN connection and firewall rules
  • SSL certificate issues: Check certificate validity and trust store
  • Connection string format: Validate connection parameters
  • Authentication failure: Verify credentials and database permissions
# Debug database connection mcp debug database --connection-test mcp logs database --level debug # Test connectivity manually telnet db.company.com 1521 openssl s_client -connect db.company.com:1521

📱 GitHub API Issues

Symptoms: Cannot access repositories or API rate limits exceeded

Common Causes & Solutions:

  • Token expiration: Rotate API tokens regularly
  • Rate limiting: Implement request throttling and caching
  • Permission scope: Verify token has required repository access
  • Enterprise GitHub URL: Check correct GitHub Enterprise URL
# Verify GitHub token curl -H "Authorization: token $GITHUB_TOKEN" \ https://github.company.com/api/v3/user # Check rate limits mcp status github --rate-limits

📄 SharePoint Authentication

Symptoms: SharePoint MCP server returns 401/403 errors

Common Causes & Solutions:

  • App registration: Verify Azure AD app permissions
  • Client secret expiration: Renew expired client secrets
  • Site permissions: Ensure service account has site access
  • Multi-factor authentication: Configure app-specific passwords
# Test SharePoint authentication mcp auth test sharepoint mcp config sharepoint --verify-permissions

Performance Issues

Diagnose and resolve performance bottlenecks

🐌 Slow Query Performance

Symptoms: MCP queries taking longer than expected

Diagnostic Steps:

# Enable query profiling mcp config database --enable-profiling # Monitor query performance mcp metrics database --queries mcp logs database --filter "slow_query" # Check connection pool status mcp status database --connection-pool

Optimization Strategies:

  • Increase connection pool size
  • Enable query result caching
  • Optimize database indexes
  • Use read replicas for queries

💾 Memory Usage

Symptoms: High memory consumption or out-of-memory errors

Memory Monitoring:

# Check memory usage mcp metrics system --memory ps aux | grep mcp # Monitor heap usage (if applicable) mcp debug --heap-dump mcp config --max-memory 2048M

Memory Optimization:

  • Reduce cache size limits
  • Implement streaming for large results
  • Tune garbage collection settings
  • Monitor for memory leaks

🌐 Network Latency

Symptoms: High response times due to network delays

Network Diagnostics:

# Test network latency ping db.company.com traceroute github.company.com mcp network-test --all-servers # Check bandwidth utilization iftop -i eth0 mcp metrics network --bandwidth

Latency Reduction:

  • Deploy MCP servers closer to data sources
  • Use CDN for static content
  • Implement connection keep-alive
  • Optimize payload sizes

Configuration Problems

Fix common configuration and setup issues

⚙️ Invalid Configuration

Symptoms: MCP servers fail to start or behave unexpectedly

# Validate configuration mcp config validate --all mcp config test --dry-run # Check configuration syntax yamllint mcp-config.yaml jsonlint mcp-servers.json

Common configuration errors:

  • YAML indentation issues
  • Missing required fields
  • Invalid connection strings
  • Incorrect file paths

🔐 SSL/TLS Certificate Issues

Symptoms: SSL handshake failures or certificate errors

# Check certificate validity openssl x509 -in cert.pem -text -noout mcp ssl-check --server database # Verify certificate chain openssl verify -CAfile ca-bundle.crt cert.pem # Update certificate store mcp certs update mcp config ssl --ca-bundle /path/to/ca-bundle.crt

🔑 Authentication Configuration

Symptoms: Authentication failures or permission denied errors

# Test authentication mcp auth verify --all-servers mcp auth refresh --server github # Check token permissions mcp auth scope --token $GITHUB_TOKEN mcp auth test --server sharepoint --verbose

IDE Integration Issues

Resolve problems with VSCode, IntelliJ, and Eclipse integration

💻 VSCode Extension Problems

Symptoms: MCP extension not working or GitHub Copilot integration fails

# Check extension status code --list-extensions | grep mcp mcp vscode-status # Reset extension settings code --reset-extensions mcp vscode-config --reset

Common fixes:

  • Reload VSCode window
  • Update MCP extension
  • Check settings.json configuration
  • Verify server endpoints

🔧 GitHub Copilot Integration

Symptoms: Copilot not using MCP context or giving incorrect suggestions

# Verify Copilot-MCP connection mcp copilot-status mcp test-copilot-integration # Check Copilot logs code --enable-logging tail -f ~/.vscode/logs/*/copilot.log

Troubleshooting steps:

  • Restart Copilot service
  • Clear Copilot cache
  • Verify MCP server status
  • Check enterprise Copilot settings

🛠️ IntelliJ/Eclipse Setup

Symptoms: MCP plugin not loading or functioning properly

# IntelliJ debugging mcp intellij-logs mcp plugin-status --ide intellij # Eclipse debugging mcp eclipse-workspace-check mcp plugin-verify --ide eclipse

Common solutions:

  • Restart IDE with fresh workspace
  • Update MCP plugin version
  • Check Java version compatibility
  • Verify plugin installation

Debugging & Logging

Comprehensive debugging techniques for MCP issues

Enable Debug Logging

Configure detailed logging for troubleshooting:

# Enable debug mode export MCP_DEBUG=true export MCP_LOG_LEVEL=debug # Start servers with verbose logging mcp start --debug --log-file /var/log/mcp.log # Tail logs in real-time tail -f /var/log/mcp.log | grep ERROR mcp logs --follow --filter "authentication"

Health Checks & Monitoring

Regular health monitoring and alerting setup:

# Run comprehensive health check mcp health-check --all --verbose # Set up monitoring dashboard mcp monitor --dashboard --port 8080 # Configure alerts mcp alerts configure --email admin@company.com mcp alerts add --name "server_down" --condition "status != healthy"

Getting Help

Resources for additional support and assistance

📞 Internal Support

  • IT Help Desk: Submit tickets for infrastructure issues
  • DevOps Team: Contact for deployment and configuration help
  • Security Team: Consult for authentication and compliance questions
  • Architecture Team: Discuss integration patterns and best practices

📚 Documentation

🤝 Community Resources

  • Internal Forums: Developer community discussions
  • Slack Channels: Real-time chat support (#mcp-support)
  • Office Hours: Weekly Q&A sessions with MCP experts
  • Training Sessions: Regular workshops and webinars