AI Client Troubleshooting

This guide covers issues specific to AI client integration with the WhoisXML API MCP Server. While the server itself may work correctly, various AI clients can have unique integration challenges and configuration requirements.

Quick Resolution Steps

Most AI client issues can be resolved by:

  1. Restarting the client completely after configuration changes
  2. Check JSON syntax in configuration files
  3. Verify API token is correct and properly set
  4. Test server independently before blaming the client

General AI Client Issues

Tools Not Appearing in Client

Symptoms:

  • MCP server starts but no tools appear in the AI client
  • Client doesn't recognize the MCP server
  • Empty tool list or missing functionality

Diagnosis:

# Test server independently first
docker run --rm -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

# Check configuration file syntax
python -m json.tool your-config.json
# or
jq . your-config.json

# Verify server executable path
ls -la /path/to/mcp-whoisxmlapi
which mcp-whoisxmlapi

Solutions:

  1. Restart client completely:

    # Completely quit and restart the AI client
# Don't just reload - do a full restart

  2. Verify configuration file location:

    • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
    • Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
    • Cursor: .cursor/mcp.json in project or ~/.cursor/mcp.json

  3. Check JSON syntax:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env", "WHOISXMLAPI_TOKEN", "whoisxmlapidotcom/mcp-whoisxmlapi:v1"],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token-here"
      }
    }
  }
}

Authentication Failures

Symptoms:

  • "Authentication failed" or "Invalid API token" errors
  • Server starts but all requests fail
  • "API key token environment variable is required"

Diagnosis:

# Check environment variable
echo $WHOISXMLAPI_TOKEN

# Test token format (should start with specific prefix)
echo "Token length: ${#WHOISXMLAPI_TOKEN}"

# Test server with token
WHOISXMLAPI_TOKEN=your-token mcp-whoisxmlapi --help

Solutions:

  1. Verify token format:

    # Token should be properly formatted
# Check for extra spaces, quotes, or newlines
echo "$WHOISXMLAPI_TOKEN" | hexdump -C

  2. Check token configuration in client:

    {
  "env": {
    "WHOISXMLAPI_TOKEN": "your-actual-token-without-quotes"
  }
}

Client Crashes or Timeouts

Symptoms:

  • AI client crashes when MCP server is enabled
  • Client becomes unresponsive
  • Long delays when using MCP tools

Solutions:

  1. Reduce tool count:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "mcp-whoisxmlapi",
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token",
        "WHOISXMLAPI_DISABLED_TOOLS": "threat_intelligence,reverse_whois,whois_history"
      }
    }
  }
}

  2. Increase timeout:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "mcp-whoisxmlapi",
      "args": ["--timeout", "30s"],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token"
      }
    }
  }
}

  3. Check client status page:

    # Many AI services have status pages
# Check for ongoing issues

Claude Desktop Issues

Configuration File Not Found

Symptoms:

  • Changes to configuration don't take effect
  • Claude Desktop doesn't see MCP servers
  • "No MCP servers configured" message

Solutions:

  1. Create configuration directory:

    # macOS
mkdir -p ~/Library/Application\ Support/Claude/

# Windows
mkdir %APPDATA%\Claude\

  2. Use correct filename:

    # Must be exactly: claude_desktop_config.json
# Not: config.json or claude-config.json

  3. Verify file location:

    # macOS
ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
dir %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop Won't Start MCP Server

Symptoms:

  • Claude Desktop starts but MCP server doesn't
  • No error messages visible
  • Tools don't appear

Diagnosis:

# Test MCP server configuration independently
docker run --rm -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

# Check Claude Desktop logs (macOS)
tail -f ~/Library/Logs/Claude/main.log

Solutions:

  1. Restart Claude Desktop completely:

    # macOS: Quit completely and restart
# Windows: Exit from system tray and restart

  2. Check Docker is running:

    docker info
docker ps

  3. Use absolute paths:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "/usr/local/bin/docker",
      "args": ["run", "--rm", "-i", "--env", "WHOISXMLAPI_TOKEN", "whoisxmlapidotcom/mcp-whoisxmlapi:v1"],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token"
      }
    }
  }
}

Cursor Issues

MCP Server Not Detected

Symptoms:

  • Cursor doesn't show MCP server configuration
  • No MCP tools available
  • Configuration changes ignored

Solutions:

  1. Check configuration file location:

    # Project-specific
ls -la .cursor/mcp.json

# Global
ls -la ~/.cursor/mcp.json

  2. Use Cursor's MCP interface:

    # Use Cursor's built-in MCP configuration UI
# Command Palette: "MCP: Configure Servers"

  3. Restart Cursor completely:

    # Close all windows and restart
# Check if MCP servers appear in settings

Cursor MCP Configuration UI Issues

Symptoms:

  • Can't add servers through UI
  • UI doesn't save configuration
  • Manual file configuration preferred

Solutions:

  1. Manual configuration:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env", "WHOISXMLAPI_TOKEN", "whoisxmlapidotcom/mcp-whoisxmlapi:v1"],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token"
      }
    }
  }
}

  2. Reload Cursor window:

    # Command Palette: "Developer: Reload Window"

Claude Code Issues

CLI Installation Problems

Symptoms:

  • claude mcp add command fails
  • Claude Code not recognizing MCP server
  • npm or Node.js issues

Diagnosis:

# Check Claude Code installation
claude --version

# Check Node.js version
node --version

# Test MCP server independently
npx @whoisxmlapidotcom/mcp-whoisxmlapi --help

Solutions:

  1. Update Claude Code:

    npm update -g claude-cli
# or
npm install -g claude-cli@latest

  2. Use direct MCP configuration:

    claude mcp add whoisxmlapi \
  --env WHOISXMLAPI_TOKEN=your-token \
  -- npx -y @whoisxmlapidotcom/mcp-whoisxmlapi

  3. Check Node.js requirements:

    # Ensure Node.js 22+ LTS is installed
node --version

Claude Code Authentication Issues

Symptoms:

  • "Authentication required" for Claude Code itself
  • MCP server works but Claude Code doesn't
  • API key issues for Claude Code

Solutions:

  1. Re-authenticate Claude Code:

    claude auth login
claude auth status

  2. Check Claude Code API access:

    # Verify Claude Code can make API calls
claude chat "Hello, test message"

  3. Update authentication:

    claude auth logout
claude auth login

Gemini CLI Issues

Gemini API Key Issues

Symptoms:

  • Gemini CLI fails with authentication errors
  • "Invalid API key" messages
  • Can't access Gemini services

Solutions:

  1. Get valid Gemini API key:

    # Visit: https://makersuite.google.com/app/apikey
# Create new API key
export GOOGLE_API_KEY="your-key-here"

  2. Test API key:

    curl -H "Authorization: Bearer $GOOGLE_API_KEY" \
  "https://generativelanguage.googleapis.com/v1/models"

VS Code Extension Issues

MCP Integration with VS Code Extensions

Symptoms:

  • VS Code AI extensions don't see MCP server
  • Extension-specific configuration issues
  • MCP servers work in other clients but not VS Code

Solutions:

  1. Check extension documentation:

    # Each VS Code AI extension has different MCP support
# Check specific extension documentation for MCP configuration

  2. Use standard MCP configuration:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "npx",
      "args": ["-y", "@whoisxmlapidotcom/mcp-whoisxmlapi"],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token"
      }
    }
  }
}

  3. Extension-specific settings:

    // In VS Code settings.json
{
  "extension.mcp.servers": {
    "whoisxmlapi": {
      "command": "npx",
      "args": ["-y", "@whoisxmlapidotcom/mcp-whoisxmlapi"],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token"
      }
    }
  }
}

Performance and Scaling Issues

Too Many Tools Error

Symptoms:

  • "Too many tools" error from AI client
  • Client refuses to load all MCP tools
  • Performance degradation with many tools

Solutions:

  1. Disable unused tools:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "mcp-whoisxmlapi",
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token",
        "WHOISXMLAPI_DISABLED_TOOLS": "threat_intelligence,reverse_whois,whois_history,ssl_certificates"
      }
    }
  }
}

  2. Prioritize essential tools:

    # Keep only most important tools
WHOISXMLAPI_DISABLED_TOOLS="threat_intelligence,reverse_whois,whois_history,dns_history,reverse_ip,reverse_mx,reverse_ns,reverse_dns,ip_netblocks"

  3. Split into multiple servers:

    {
  "mcpServers": {
    "whoisxmlapi-basic": {
      "command": "mcp-whoisxmlapi",
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token",
        "WHOISXMLAPI_DISABLED_TOOLS": "threat_intelligence,reverse_whois,whois_history,dns_history,ssl_certificates,ip_netblocks,subdomain_lookup,domain_and_subdomain_discovery"
      }
    },
    "whoisxmlapi-advanced": {
      "command": "mcp-whoisxmlapi",
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token",
        "WHOISXMLAPI_DISABLED_TOOLS": "whois,categorization,email_verification,dns_lookup,ipgeolocation,reverse_ip,reverse_mx,reverse_ns,reverse_dns"
      }
    }
  }
}

Client Memory Issues

Symptoms:

  • AI client crashes with memory errors
  • Slow performance when MCP is enabled
  • Client becomes unresponsive

Solutions:

  1. Increase client memory limits:

    # For desktop apps, check system memory
# Close other applications

  2. Reduce MCP server resource usage:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--memory=256m",
        "--cpus=0.5",
        "--env", "WHOISXMLAPI_TOKEN",
        "whoisxmlapidotcom/mcp-whoisxmlapi:v1"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token"
      }
    }
  }
}

Debugging and Diagnostics

Client-Specific Debugging

Claude Desktop:

# Check logs (macOS)
tail -f ~/Library/Logs/Claude/main.log

# Check configuration
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

Cursor:

# Check logs
# Help → Toggle Developer Tools → Console

# Check configuration
cat .cursor/mcp.json
cat ~/.cursor/mcp.json

Claude Code:

# Check CLI status
claude --version
claude auth status

# List MCP servers
claude mcp list

# Test specific server
claude mcp test whoisxmlapi

MCP Server Testing

# Test server independently with each method
docker run --rm -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

npx @whoisxmlapidotcom/mcp-whoisxmlapi --help

/usr/local/bin/mcp-whoisxmlapi --help

# Test with actual token
WHOISXMLAPI_TOKEN=your-real-token mcp-whoisxmlapi --help

Configuration Validation

# Validate JSON syntax
python -m json.tool config.json
jq . config.json

# Check file permissions
ls -la config.json

# Verify paths exist
ls -la /path/specified/in/config
which mcp-whoisxmlapi

Prevention and Best Practices

Configuration Best Practices

  1. Always restart clients after configuration changes
  2. Use absolute paths in configuration files
  3. Test server independently before integrating
  4. Keep tokens secure and separate from configuration files when possible
  5. Start with minimal configuration and add features incrementally

Testing Workflow

# 1. Test server independently
mcp-whoisxmlapi --help

# 2. Test with token
WHOISXMLAPI_TOKEN=your-token mcp-whoisxmlapi --help

# 3. Test configuration syntax
python -m json.tool config.json

# 4. Restart client completely

# 5. Test one tool at a time

Monitoring and Maintenance

  1. Enable HTTP debugging when troubleshooting:

    {
  "env": {
    "WHOISXMLAPI_HTTP_DEBUG": "/tmp/whoisxmlapi-debug.log"
  }
}

  2. Regular updates:

    # Update MCP server
docker pull whoisxmlapidotcom/mcp-whoisxmlapi:v1
npx -y @whoisxmlapidotcom/mcp-whoisxmlapi

# Update AI clients
# Check for client updates regularly

Getting Help

Information to Collect

When seeking help with AI client issues:

  1. Client information:

    • AI client name and version
    • Operating system
    • Configuration file contents (remove tokens)

  2. Server testing:

    # Test server independently
mcp-whoisxmlapi --version
WHOISXMLAPI_TOKEN=test mcp-whoisxmlapi --help

  3. Error messages:

    • Client error messages
    • Console logs
    • Server logs if available

  4. Configuration:

    // Your configuration (remove actual tokens)
{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "...",
      "env": {
        "WHOISXMLAPI_TOKEN": "REDACTED"
      }
    }
  }
}
Last Updated: