Skip to Content
Troubleshooting

Troubleshooting

Common issues and solutions for Tetrix AI MCP Server integration. Find quick fixes for connection problems, configuration errors, and performance issues.

Quick Diagnostics

Check System Requirements

Before troubleshooting, verify your system meets the requirements:

# Check Node.js version (requires 18+)
node --version
 
# Check npx availability
npx --version
 
# Test internet connectivity
curl -I http://tetrix-level-1-dev-alb-463220232.us-east-1.elb.amazonaws.com/mcp

Verify Configuration

Common configuration issues:

  1. JSON Syntax: Validate your configuration file
  2. File Location: Ensure config is in the correct directory
  3. Permissions: Check file read permissions

Connection Issues

Problem: “Cannot connect to MCP server”

Symptoms:

  • MCP client shows “connection failed” or similar error
  • Tetrix AI features not available in your AI platform

Solutions:

  1. Check Internet Connection

    # Test basic connectivity
ping google.com
 
# Test Tetrix AI endpoint
curl http://tetrix-level-1-dev-alb-463220232.us-east-1.elb.amazonaws.com/mcp

  2. Verify Configuration

    • Ensure JSON syntax is correct
    • Check that all quotes are double quotes
    • Validate file location for your platform

  3. Restart Your Client

    • Close your AI platform completely
    • Reopen and wait 30-60 seconds for connection

Problem: “Command not found: npx”

Symptoms:

  • Error mentioning npx command not found
  • MCP server fails to start

Solutions:

  1. Install Node.js

    # Download from nodejs.org or use package manager
# macOS with Homebrew:
brew install node
 
# Ubuntu/Debian:
sudo apt install nodejs npm

  2. Verify Installation

    node --version  # Should show v18 or higher
npm --version   # Should show npm version
npx --version   # Should show npx version

  3. Update PATH

    # Add Node.js to PATH if needed
export PATH=$PATH:/usr/local/bin/node

Problem: “Connection timeout”

Symptoms:

  • Connection attempts time out
  • Slow or no response from Tetrix AI

Solutions:

  1. Check Network Settings

    • Verify firewall allows outbound HTTP connections
    • Check if corporate proxy is blocking requests
    • Test from different network if possible

  2. Increase Timeout

    {
  "mcpServers": {
    "tetrix": {
      "command": "npx",
      "args": [...],
      "timeout": 60000,
      "env": {
        "TETRIX_TIMEOUT": "45000"
      }
    }
  }
}

Configuration Problems

Problem: “Invalid JSON in configuration file”

Symptoms:

  • Configuration file not recognized
  • Syntax error messages

Solutions:

  1. Validate JSON Syntax

    # Use jq to validate JSON
cat your-config.json | jq .
 
# Or use online JSON validator

  2. Common JSON Mistakes

    // ❌ Wrong - single quotes
{ 'mcpServers': { 'tetrix': {...} } }
 
// ❌ Wrong - trailing comma
{ "mcpServers": { "tetrix": {...}, } }
 
// ✅ Correct
{ "mcpServers": { "tetrix": {...} } }

  3. Use Configuration Template Copy the exact configuration from our guides to avoid syntax errors.

Problem: “Configuration file not found”

Symptoms:

  • Changes to configuration don’t take effect
  • Client doesn’t recognize MCP servers

Solutions:

  1. Verify File Location

    Claude Desktop:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

    Cursor:

    • Look for MCP settings in Cursor preferences
    • Check settings.json file location

  2. Create Missing File

    # Create directory if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude/
 
# Create basic config file
echo '{}' > ~/Library/Application\ Support/Claude/claude_desktop_config.json

  3. Check File Permissions

    # Ensure file is readable
chmod 644 ~/Library/Application\ Support/Claude/claude_desktop_config.json

Platform-Specific Issues

Claude Desktop Issues

Problem: Claude Desktop doesn’t show MCP servers

  1. Check Claude Desktop Version

    • Ensure you have a version that supports MCP
    • Update Claude Desktop if needed

  2. Restart Claude Desktop

    • Quit Claude Desktop completely
    • Wait 10 seconds
    • Reopen Claude Desktop

  3. Check Configuration Location

    # Verify config file exists and has content
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

Cursor Issues

Problem: Cursor doesn’t recognize MCP configuration

  1. Check Cursor Version

    • Ensure Cursor supports MCP integration
    • Update Cursor if needed

  2. Verify Settings Location

    • Open Cursor settings
    • Search for “MCP” or “Model Context Protocol”
    • Ensure configuration is in correct section

  3. Restart Cursor

    • Close all Cursor windows
    • Restart Cursor completely

Performance Issues

Problem: “Slow responses from Tetrix AI”

Symptoms:

  • Long wait times for responses
  • Timeouts on complex queries

Solutions:

  1. Check Internet Speed

    # Test download speed
curl -o /dev/null -s -w '%{speed_download}\n' http://speedtest.wdc01.softlayer.com/downloads/test100.zip

  2. Optimize Configuration

    {
  "mcpServers": {
    "tetrix": {
      "command": "npx",
      "args": [...],
      "env": {
        "TETRIX_CACHE_ENABLED": "true",
        "TETRIX_TIMEOUT": "30000",
        "TETRIX_POOL_SIZE": "3"
      }
    }
  }
}

  3. Simplify Queries

    • Break complex questions into smaller parts
    • Be more specific about what you need
    • Avoid very broad or vague requests

Problem: “High memory usage”

Solutions:

  1. Set Memory Limits

    {
  "mcpServers": {
    "tetrix": {
      "command": "npx",
      "args": [...],
      "env": {
        "NODE_OPTIONS": "--max-old-space-size=512",
        "TETRIX_MAX_MEMORY": "256MB"
      }
    }
  }
}

  2. Monitor Resource Usage

    # Monitor Node.js processes
ps aux | grep node
 
# Check memory usage
top -p $(pgrep -f "mcp-remote")

Error Messages

”ECONNREFUSED” or “ENOTFOUND”

Cause: Network connectivity issues

Solutions:

  1. Check internet connection
  2. Verify DNS resolution
  3. Check firewall settings
  4. Try different network

”ETIMEDOUT”

Cause: Request timeout

Solutions:

  1. Increase timeout values
  2. Check network latency
  3. Try during different time periods
  4. Contact support if persistent

”EACCES” or “Permission denied”

Cause: File permission issues

Solutions:

  1. Check file permissions
  2. Run with appropriate user permissions
  3. Verify directory access
  4. Check parent directory permissions

”MODULE_NOT_FOUND”

Cause: Missing Node.js modules

Solutions:

  1. Clear npm cache: npm cache clean --force
  2. Update npm: npm install -g npm@latest
  3. Try manual installation: npm install -g mcp-remote

Advanced Troubleshooting

Debug Logging

Enable detailed logging to diagnose issues:

{
  "mcpServers": {
    "tetrix": {
      "command": "npx",
      "args": [...],
      "env": {
        "DEBUG": "tetrix:*,mcp:*",
        "TETRIX_LOG_LEVEL": "debug",
        "NODE_ENV": "development"
      }
    }
  }
}

Manual Testing

Test the MCP connection manually:

# Test direct connection
npx -y mcp-remote@latest http://tetrix-level-1-dev-alb-463220232.us-east-1.elb.amazonaws.com/mcp --transport http-only --allow-http
 
# Test with verbose output
DEBUG=* npx -y mcp-remote@latest http://tetrix-level-1-dev-alb-463220232.us-east-1.elb.amazonaws.com/mcp --transport http-only --allow-http

Network Diagnostics

# Test DNS resolution
nslookup tetrix-level-1-dev-alb-463220232.us-east-1.elb.amazonaws.com
 
# Test HTTP connectivity
curl -v http://tetrix-level-1-dev-alb-463220232.us-east-1.elb.amazonaws.com/mcp
 
# Check routing
traceroute tetrix-level-1-dev-alb-463220232.us-east-1.elb.amazonaws.com

Getting Additional Help

Before Requesting Help

Please gather this information:

  1. System Information

    • Operating system and version
    • Node.js version (node --version)
    • AI platform and version

  2. Configuration

    • Your MCP configuration (remove any sensitive data)
    • File location and permissions

  3. Error Details

    • Exact error messages
    • Steps to reproduce
    • When the issue started

Support Channels

Community Resources

  • FAQ: Check our frequently asked questions
  • Examples: Browse working configuration examples
  • Best Practices: Learn from community experiences

Still having issues? Don’t hesitate to reach out to our community or support team. We’re here to help you get Tetrix AI working perfectly with your setup.

Last updated on
ConfigurationContact Us