MCP Troubleshooting Guide

This comprehensive troubleshooting guide helps you resolve common issues with Model Context Protocol (MCP) integration in Consultia.

Quick Diagnosis

Connection Issues

  • Cannot connect to MCP server
  • Authentication failed
  • Network timeout errors

Data Access Issues

  • Permission denied errors
  • Empty query results
  • Data not found errors

Performance Issues

  • Slow response times
  • Rate limit exceeded
  • High latency

Configuration Issues

  • Invalid API key format
  • Missing permissions
  • Expired API keys

Connection Issues

Problem: Cannot Connect to MCP Server

Symptoms:

  • Claude Desktop shows "Connection failed" error
  • Network timeout when trying to connect
  • Server unreachable error messages

Diagnostic Steps:

  1. Check Server URL

    # Test server connectivity
curl -I https://your-domain.com/api/mcp

# Expected response:
# HTTP/2 200
# Content-Type: application/json

  2. Verify Network Connectivity

    # Test basic connectivity
ping your-domain.com

# Test DNS resolution
nslookup your-domain.com

# Test port connectivity
telnet your-domain.com 443

  3. Check Firewall Settings

    • Ensure port 443 is open for outbound HTTPS
    • Verify no corporate firewall blocking the connection
    • Check VPN settings if using corporate network

Solutions:

  1. Correct Server URL

    ✅ Production: https://your-domain.com/api/mcp
✅ Development: http://localhost:3000/api/mcp
❌ Wrong: https://your-domain.com/mcp
❌ Wrong: http://your-domain.com/api/mcp (no HTTPS)

  2. Network Configuration

    # Add to /etc/hosts for local testing
127.0.0.1 localhost

# Configure proxy if needed
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

  3. VPN Configuration

    • Connect to corporate VPN before testing
    • Ensure VPN allows HTTPS traffic to external domains
    • Check VPN split tunneling settings

Problem: Authentication Failed

Symptoms:

  • "Invalid API key" error messages
  • "Authentication failed" responses
  • 401 Unauthorized HTTP status codes

Diagnostic Steps:

  1. Verify API Key Format

    # API key should start with 'ck_' and be 64 characters
echo "ck_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" | wc -c
# Expected: 67 (including newline)

  2. Check API Key Validity

    • Log into Consultia
    • Go to Integrations > MCP Settings
    • Verify API key exists and is active
    • Check if key has expired

  3. Test API Key

    # Test with curl
curl -X POST https://your-domain.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ck_your_api_key_here" \
  -d '{"method": "tools/list"}'

Solutions:

  1. Regenerate API Key

    • Go to MCP Settings > API Key Management
    • Click "Create New API Key"
    • Copy the new key immediately
    • Update Claude Desktop configuration

  2. Check Key Permissions

    • Ensure API key has required permissions
    • Add missing permissions if needed
    • Verify key is not revoked

  3. Update Configuration

    • Update Claude Desktop with new API key
    • Clear any cached authentication data
    • Restart Claude Desktop application

Data Access Issues

Problem: Permission Denied Errors

Symptoms:

  • "Insufficient permissions to access customer data"
  • "Permission denied for this operation"
  • 403 Forbidden HTTP status codes

Common Error Messages:

{
  "success": false,
  "error": "Insufficient permissions to access customer data",
  "error_code": "PERMISSION_DENIED",
  "execution_time_ms": 12
}

Diagnostic Steps:

  1. Check API Key Permissions

    # List required permissions for each tool
- query_crm_data: READ_CUSTOMERS, READ_INVOICES, READ_PAYMENTS
- get_crm_analytics: READ_CUSTOMERS, READ_INVOICES, READ_PAYMENTS
- execute_crm_action: EXECUTE_ACTIONS

  2. Verify User Permissions

    • Check if user account has MCP access
    • Verify user belongs to correct customer organization
    • Ensure user account is active

Solutions:

  1. Update API Key Permissions

    • Go to MCP Settings > API Key Management
    • Find your API key and click "Edit"
    • Add required permissions:
      • ✅ READ_CUSTOMERS
      • ✅ READ_INVOICES
      • ✅ READ_PAYMENTS
      • ✅ EXECUTE_ACTIONS (if needed)
    • Click "Update"

  2. Create New API Key with Correct Permissions

    • Generate new API key with all required permissions
    • Update Claude Desktop configuration
    • Test with simple query first

Problem: Empty Query Results

Symptoms:

  • Queries return empty data arrays
  • "No data found" messages
  • Zero count results

Diagnostic Steps:

  1. Check Data Existence

    // Test with minimal filters
{
  "method": "tools/call",
  "params": {
    "name": "query_crm_data",
    "arguments": {
      "entity": "customers",
      "filters": {},
      "limit": 10
    }
  }
}

  2. Verify Tenant Isolation

    • Ensure you're querying data for correct customer organization
    • Check if data exists for your consultiaCustomerId
    • Verify data is not archived

  3. Check Filter Logic

    // Common filter issues
{
  "filters": {
    "isArchived": false,  // ✅ Correct
    "status": "ACTIVE"    // ❌ Wrong field name
  }
}

Solutions:

  1. Use Correct Entity Names

    // Supported entities
"entity": "customers"     // ✅ Correct
"entity": "invoices"      // ✅ Correct
"entity": "payments"      // ✅ Correct
"entity": "resources"     // ✅ Correct
"entity": "products"      // ✅ Correct

  2. Remove Restrictive Filters

    // Start with no filters
{
  "entity": "customers",
  "filters": {},
  "limit": 5
}

// Then add filters gradually
{
  "entity": "customers",
  "filters": {
    "isArchived": false
  },
  "limit": 5
}

  3. Check Data Status

    • Verify data is not archived
    • Check if data belongs to your organization
    • Ensure data was created recently

Performance Issues

Problem: Slow Response Times

Symptoms:

  • Queries take more than 5 seconds
  • Timeout errors
  • High latency indicators

Diagnostic Steps:

  1. Check Network Latency

    # Test network latency
ping your-domain.com

# Test HTTP latency
curl -w "@curl-format.txt" -o /dev/null -s https://your-domain.com/api/mcp

  2. Monitor Query Complexity

    // Simple query (fast)
{
  "entity": "customers",
  "limit": 10
}

// Complex query (slower)
{
  "entity": "customers",
  "filters": {
    "purchaseOrders": {
      "some": {
        "invoices": {
          "some": {
            "status": "PAID"
          }
        }
      }
    }
  },
  "include": {
    "purchaseOrders": {
      "include": {
        "invoices": true
      }
    }
  }
}

Solutions:

  1. Optimize Queries

    // Use pagination for large datasets
{
  "entity": "customers",
  "limit": 20,
  "offset": 0
}

// Use specific filters
{
  "entity": "customers",
  "filters": {
    "createdAt": {
      "gte": "2024-01-01T00:00:00Z"
    }
  }
}

  2. Network Optimization

    • Use wired connection instead of WiFi
    • Connect to corporate VPN if required
    • Check for network congestion

  3. Server Performance

    • Contact support if server performance is consistently poor
    • Check server status page for known issues
    • Monitor server response times over time

Problem: Rate Limit Exceeded

Symptoms:

  • "Rate limit exceeded" error messages
  • 429 Too Many Requests HTTP status codes
  • Temporary blocking of requests

Error Message:

{
  "success": false,
  "error": "Rate limit exceeded. Please try again later.",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}

Solutions:

  1. Respect Rate Limits

    • Limit: 100 requests per minute per API key
    • Implement exponential backoff
    • Wait for retry_after seconds before retrying

  2. Optimize Request Frequency

    // Example: Implement rate limiting
const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));

async function makeRequest() {
  try {
    const response = await fetch('/api/mcp', options);
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      await delay(retryAfter * 1000);
      return makeRequest(); // Retry
    }
    return response;
  } catch (error) {
    console.error('Request failed:', error);
  }
}

  3. Use Caching

    • Cache frequently requested data
    • Implement client-side caching
    • Use appropriate cache headers

Configuration Issues

Problem: Invalid API Key Format

Symptoms:

  • "Invalid API key format" errors
  • Authentication failures
  • Malformed key errors

Diagnostic Steps:

  1. Check Key Format

    # API key should be exactly 64 characters after 'ck_' prefix
echo "ck_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" | wc -c
# Should be 67 (including newline and 'ck_' prefix)

  2. Verify Key Structure

    # Check for valid characters (hexadecimal)
echo "ck_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" | grep -E "^ck_[a-f0-9]{64}$"

Solutions:

  1. Regenerate API Key

    • Go to MCP Settings > API Key Management
    • Delete the invalid key
    • Create new API key
    • Copy the complete key including 'ck_' prefix

  2. Update Configuration

    • Update Claude Desktop with new key
    • Ensure no extra spaces or characters
    • Test connection immediately

Problem: Missing Permissions

Symptoms:

  • "Missing required permissions" errors
  • Tool execution failures
  • Permission-related error messages

Diagnostic Steps:

  1. Check Required Permissions

    // Tools and their required permissions
{
  "list_tools": [],
  "call_tool": [],
  "query_crm_data": ["READ_CUSTOMERS", "READ_INVOICES", "READ_PAYMENTS"],
  "get_crm_analytics": ["READ_CUSTOMERS", "READ_INVOICES", "READ_PAYMENTS"],
  "execute_crm_action": ["EXECUTE_ACTIONS"]
}

  2. Verify Current Permissions

    • Go to MCP Settings > API Key Management
    • Check current permissions for your API key
    • Compare with required permissions

Solutions:

  1. Add Missing Permissions

    • Edit API key permissions
    • Add required permissions
    • Save changes

  2. Create New Key with Full Permissions

    • Generate new API key with all permissions
    • Update Claude Desktop configuration
    • Test all required tools

Error Code Reference

Common Error Codes

Error Code Description Solution
PERMISSION_DENIED Insufficient permissions Add required permissions to API key
INVALID_PARAMETERS Invalid or missing parameters Check parameter format and requirements
ENTITY_NOT_FOUND Requested entity not found Verify entity name and existence
VALIDATION_ERROR Data validation failed Check input data format and constraints
RATE_LIMIT_EXCEEDED API rate limit exceeded Wait and retry with exponential backoff
INTERNAL_ERROR Internal server error Contact support with error details
AUTHENTICATION_FAILED Invalid API key or authentication Regenerate and update API key
NETWORK_ERROR Network connectivity issue Check network connection and firewall

HTTP Status Codes

Status Code Meaning Action
200 Success Continue normal operation
400 Bad Request Check request parameters
401 Unauthorized Verify API key and authentication
403 Forbidden Check API key permissions
404 Not Found Verify endpoint URL and entity names
429 Too Many Requests Implement rate limiting and retry
500 Internal Server Error Contact support
502 Bad Gateway Check server connectivity
503 Service Unavailable Wait and retry later

Debugging Tools

Connection Testing

  1. Use Connection Tester

    • Go to MCP Settings in Consultia
    • Use the Connection Tester component
    • Check latency and status indicators

  2. Test with curl

    # Test basic connectivity
curl -I https://your-domain.com/api/mcp

# Test with API key
curl -X POST https://your-domain.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ck_your_api_key" \
  -d '{"method": "tools/list"}'

  3. Check Audit Logs

    • Review MCP operation logs in Consultia
    • Look for failed authentication attempts
    • Check for permission violations

Performance Monitoring

  1. Usage Dashboard

    • Monitor API usage statistics
    • Check response times and error rates
    • Review usage patterns

  2. Network Diagnostics

    # Test network performance
traceroute your-domain.com

# Check DNS resolution
dig your-domain.com

# Test SSL connection
openssl s_client -connect your-domain.com:443

Getting Help

Self-Service Resources

  1. Documentation

  2. Community Support

    • Check community forums for similar issues
    • Search existing knowledge base articles
    • Review FAQ sections

Contact Support

When contacting support, provide:

  1. Error Details

    • Complete error message
    • Error code and HTTP status
    • Timestamp of occurrence

  2. Environment Information

    • Claude Desktop version
    • Operating system
    • Network configuration
    • API key permissions

  3. Steps to Reproduce

    • Exact steps that caused the issue
    • Query parameters used
    • Expected vs actual results

  4. Logs and Screenshots

    • Audit log entries
    • Network diagnostic results
    • Screenshots of error messages

Escalation Process

  1. Initial Contact: Submit support ticket with details
  2. Triage: Support team reviews and categorizes issue
  3. Investigation: Technical team investigates root cause
  4. Resolution: Solution provided and verified
  5. Follow-up: Confirm resolution and document for future reference

Prevention Best Practices

Regular Maintenance

  1. API Key Management

    • Rotate keys every 90 days
    • Review permissions quarterly
    • Monitor usage patterns

  2. Network Monitoring

    • Check connectivity regularly
    • Monitor latency and performance
    • Update network configurations

  3. Software Updates

    • Keep Claude Desktop updated
    • Update security patches
    • Review configuration changes

Proactive Monitoring

  1. Set Up Alerts

    • Monitor for unusual API usage
    • Alert on authentication failures
    • Track performance metrics

  2. Regular Testing

    • Test basic connectivity weekly
    • Verify permissions monthly
    • Run performance benchmarks

  3. Documentation Updates

    • Keep configuration documentation current
    • Update troubleshooting procedures
    • Share lessons learned with team

Related Documentation