MCP Configuration Troubleshooting

This guide helps diagnose and resolve common issues with MCP configuration and connectivity.

Quick Diagnostics

Connection Test

Run this quick test to verify your MCP configuration:

# Test basic connectivity
curl -H "User-Id: your_user_id" \
     -H "App-Key: your_app_key" \
     -H "App-Symbol: ENGMA" \
     https://stg.onli.app/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z",
  "version": "1.0.0"
}

Configuration Validation

function validateMCPConfig(config) {
  [object Object] issues [object Object] [object Object][object Object][object Object]
[object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object]

Common Issues and Solutions

1. Authentication Errors

Issue: 401 Unauthorized

Symptoms:

{
  "error": "Unauthorized",
  "code": 401,
  "message": "Invalid or missing authentication credentials"
}

Possible Causes:

• Incorrect User ID or App Key
• Expired credentials
• Missing authentication headers

Solutions:

1. Verify Credentials

   Copy code

   # Check if credentials are properly set
   echo "User ID: $ONLI_USER_ID"
   echo "App Key: $ONLI_APP_KEY"
   echo "App Symbol: $ONLI_APP_SYMBOL"
   

2. Regenerate API Keys

   • Log into Onli Platform dashboard
   • Navigate to API Settings > MCP Configuration
   • Generate new App Key
   • Update your configuration

3. Check Header Format

   Copy code

       {
      "headers": {
        "User-Id": "user_12345",        // Correct format
        "App-Key": "ak_abcd1234...",    // Correct format
        "App-Symbol": "ENGMA"           // Correct format
      }
    }
   

Issue: 403 Forbidden

Symptoms:

{
  "error": "Forbidden",
  "code": 403,
  "message": "Insufficient permissions for requested operation"
}

Solutions:

1. Check Account Permissions

   • Verify your account has MCP access enabled
   • Contact administrator to check permission levels

2. Verify App Symbol

   Copy code

   // Ensure App Symbol matches your account configuration
   const validSymbols = ['ENGMA', 'OTHER_SYMBOL'];
   if (!validSymbols.includes(config.headers['App-Symbol'])) {
     console.error('Invalid App Symbol');
   }
   

2. Connection Issues

Issue: Network Timeouts

Symptoms:

Error: ETIMEDOUT - Connection timed out
Error: ECONNREFUSED - Connection refused

Solutions:

1. Check Network Connectivity

   Copy code

   # Test basic connectivity
   ping api.onli.app
   
   # Test HTTPS connectivity
   curl -I https://api.onli.app
   

2. Adjust Timeout Settings

   Copy code

   {
     "onli-mcp": {
       "url": "https://api.onli.app",
       "options": {
         "timeout": 30000,           // Increase timeout
         "connectionTimeout": 10000, // Connection-specific timeout
         "retries": 3               // Enable retries
       }
     }
   }
   

3. Check Firewall/Proxy Settings

   Copy code

   # If behind corporate firewall, check proxy settings
   export HTTPS_PROXY=http://proxy.company.com:8080
   export HTTP_PROXY=http://proxy.company.com:8080
   

Issue: SSL/TLS Errors

Symptoms:

Error: DEPTH_ZERO_SELF_SIGNED_CERT
Error: CERT_HAS_EXPIRED
Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE

Solutions:

1. Update Certificate Store

   Copy code

   # On Ubuntu/Debian
   sudo apt-get update && sudo apt-get install ca-certificates
   
   # On macOS
   brew update && brew upgrade
   

2. Check System Time

   Copy code

   # Ensure system time is correct
   date
   

3. Verify Certificate Chain

   Copy code

   openssl s_client -connect api.onli.app:443 -servername api.onli.app
   

3. Configuration Issues

Issue: Invalid Configuration Format

Symptoms:

Error: Configuration validation failed
Error: Invalid JSON format

Solutions:

1. Validate JSON Format

   Copy code

   # Use jq to validate JSON
   cat config.json | jq .
   

2. Check Required Fields

   Copy code

   const requiredFields = [
     'url',
     'headers.User-Id',
     'headers.App-Key', 
     'headers.App-Symbol'
   ];
   
   function checkRequired(config) {
     return requiredFields.every(field => {
       const value = field.split('.').reduce(([object Object][object Object] [object Object] obj[object Object][object Object]key[object Object][object Object] config[object Object][object Object]
   [object Object][object Object][object Object]

3. Use Configuration Template

   Copy code

   {
     "onli-mcp": {
       "url": "https://stg.onli.app",
       "headers": {
         "User-Id": "${ONLI_USER_ID}",
         "App-Key": "${ONLI_APP_KEY}",
         "App-Symbol": "${ONLI_APP_SYMBOL}"
       },
       "options": {
         "timeout": 15000,
         "retries": 3,
         "debug": false
       }
     }
   }
   

4. Environment-Specific Issues

Issue: Environment Variable Not Found

Symptoms:

Error: Environment variable ONLI_USER_ID is not defined
Error: Cannot read property of undefined

Solutions:

1. Check Environment Variables

   Copy code

   # List all ONLI-related environment variables
   env | grep ONLI
   
   # Check specific variables
   echo "User ID: ${ONLI_USER_ID:-'NOT SET'}"
   echo "App Key: ${ONLI_APP_KEY:-'NOT SET'}"
   echo "App Symbol: ${ONLI_APP_SYMBOL:-'NOT SET'}"
   

2. Load Environment File

   Copy code

   # Load from .env file
   source .env
   
   # Or use dotenv in Node.js
   require('dotenv').config();
   

3. Set Variables Manually

   Copy code

   export ONLI_USER_ID="your_user_id"
   export [object Object][object Object][object Object]
   [object Object]

Issue: Wrong Environment Endpoint

Symptoms:

• Development code hitting production endpoints
• Production errors in development environment

Solutions:

1. Environment-Specific Configuration

   Copy code

   const environments = {
     development: {
       url: 'https://stg.onli.app',
       debug: true
     },
     production: {
       url: 'https://api.onli.app',
       debug: false
     }
   };
   
   const config = environments[process.env.NODE_ENV] || environments.development;
   

2. Validate Environment

   Copy code

   [object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object]

Debugging Tools

1. Enable Debug Logging

const config = {
  "onli-mcp": {
    "url": "https://stg.onli.app",
    "headers": {
      "User-Id": "${ONLI_USER_ID}",
      "App-Key": "${ONLI_APP_KEY}",
      "App-Symbol": "ENGMA"
    },
    "options": {
      "debug": true,          // Enable debug logging
      "logRequests": true,    // Log outgoing requests
      "logResponses": true    // Log incoming responses
    }
  [object Object]
[object Object]

2. Network Debugging

# Monitor network traffic
tcpdump -i any host api.onli.app

# Use curl with verbose output
curl -v -H "User-Id: your_user_id" \
     -H "App-Key: your_app_key" \
     -H "App-Symbol: ENGMA" \
     https://stg.onli.app/health

3. Application Debugging

class MCPDebugger {
  static logRequest(config, request) {
    console.log('MCP Request:', {
      timestamp: new Date().toISOString(),
      url: config.url,
      headers: this.sanitizeHeaders(request.headers),
      method: request.method,
      body: request.body
    [object Object][object Object][object Object]
[object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object]

Error Codes Reference

Health Check Endpoints

Use these endpoints to verify service health:

Getting Additional Help

1. Collect Diagnostic Information

Before contacting support, gather:

# System information
uname -a
node --version
npm --version

# Network connectivity
curl -I https://api.onli.app

# Configuration (sanitized)
cat config.json | jq 'del(.headers["App-Key"])'

# Recent logs
tail -n 50 application.log

2. Contact Support

• Email: support@onli.one
• Subject: "MCP Configuration Issue - [Brief Description]"
• Include: Diagnostic information, error messages, configuration (without sensitive data)

3. Community Resources

• Documentation: Configuration Guides
• Best Practices: MCP Best Practices
• Forum: Onli Developer Community
• Status Page: Onli Platform Status

Preventive Measures

1. Regular Health Checks

setInterval(async () => {
  try {
    await client.healthCheck();
    console.log('MCP health check: OK');
  } catch (error) {
    console.error('MCP health check failed:', error);
    // Implement alerting logic
  }
}, 5 * 60 * 1000); // Every 5 minutes

2. Monitoring and Alerting

class MCPMonitor {
  setupAlerts() {
    // Alert on authentication failures
    this.on('auth_error', () => {
      this.sendAlert('Authentication failure detected');
    });
    
    // Alert on high error rates
    this.on('high_error_rate', (rate) => {
      this.sendAlert(`Error rate exceeded threshold: ${rate}[object Object][object Object][object Object][object Object]
[object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object]

3. Configuration Backup

# Backup configuration (without secrets)
cp config.json config.json.backup.$(date +%Y%m%d)

# Version control (excluding secrets)
git add config.json
git commit -m "Update MCP configuration"