Troubleshooting Guide 🔧

This guide helps you diagnose and resolve common issues with MCP Server.

Quick Diagnostics

Health Check

First, verify the server's health:

curl http://localhost:3000/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "homeAssistant": {
    "connected": true,
    "version": "2024.1.0"
  }
}

Common Issues

1. Connection Issues

Cannot Connect to MCP Server

Symptoms: - Server not responding - Connection refused errors - Timeout errors

Solutions:

Check if the server is running:

# For Docker installation
docker compose ps

# For manual installation
ps aux | grep mcp

Verify port availability:

# Check if port is in use
netstat -tuln | grep 3000

Check logs:

# Docker logs
docker compose logs mcp

# Manual installation logs
bun run dev

Home Assistant Connection Failed

Symptoms: - "Connection Error" in health check - Cannot control devices - State updates not working

Solutions:

Verify Home Assistant URL and token in .env:

HA_URL=http://homeassistant:8123
HA_TOKEN=your_long_lived_access_token

Test Home Assistant connection:

curl -H "Authorization: Bearer YOUR_HA_TOKEN" \
     http://your-homeassistant:8123/api/

Check network connectivity:

# For Docker setup
docker compose exec mcp ping homeassistant

2. Authentication Issues

Invalid Token

Symptoms: - 401 Unauthorized responses - "Invalid token" errors

Solutions:

Generate a new token:

curl -X POST http://localhost:3000/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'

Verify token format:

// Token should be in format:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Rate Limiting

Symptoms: - 429 Too Many Requests - "Rate limit exceeded" errors

Solutions:

Check current rate limit status:

curl -I http://localhost:3000/api/state

Adjust rate limits in configuration:

security:
  rateLimit: 100  # Increase if needed
  rateLimitWindow: 60000  # Window in milliseconds

3. Real-time Updates Issues

SSE Connection Drops

Symptoms: - Frequent disconnections - Missing state updates - EventSource errors

Solutions:

Implement proper reconnection logic:

class SSEClient {
    constructor() {
        this.connect();
    }

    connect() {
        this.eventSource = new EventSource('/subscribe_events');
        this.eventSource.onerror = this.handleError.bind(this);
    }

    handleError(error) {
        console.error('SSE Error:', error);
        this.eventSource.close();
        setTimeout(() => this.connect(), 1000);
    }
}

Check network stability:

# Monitor connection stability
ping -c 100 localhost

4. Performance Issues

High Latency

Symptoms: - Slow response times - Command execution delays - UI lag

Solutions:

Enable Redis caching:

REDIS_ENABLED=true
REDIS_URL=redis://localhost:6379

Monitor system resources:

# Check CPU and memory usage
docker stats

# Or for manual installation
top -p $(pgrep -f mcp)

Optimize database queries and caching:

// Use batch operations
const results = await Promise.all([
    cache.get('key1'),
    cache.get('key2')
]);

5. Device Control Issues

Commands Not Executing

Symptoms: - Commands appear successful but no device response - Inconsistent device states - Error messages from Home Assistant

Solutions:

Verify device availability:

curl http://localhost:3000/api/state/light.living_room

Check command syntax:

# Test basic command
curl -X POST http://localhost:3000/api/command \
  -H "Content-Type: application/json" \
  -d '{"command": "Turn on living room lights"}'

Review Home Assistant logs:

docker compose exec homeassistant journalctl -f

Debugging Tools

Log Analysis

Enable debug logging:

LOG_LEVEL=debug
DEBUG=mcp:*

Network Debugging

Monitor network traffic:

# TCP dump for API traffic
tcpdump -i any port 3000 -w debug.pcap

Performance Profiling

Enable performance monitoring:

ENABLE_METRICS=true
METRICS_PORT=9090

Getting Help

If you're still experiencing issues:

Check the GitHub Issues
Search Discussions
Create a new issue with:
Detailed description
Logs
Configuration (sanitized)
Steps to reproduce

Maintenance

Regular Health Checks

Run periodic health checks:

# Create a cron job
*/5 * * * * curl -f http://localhost:3000/health || notify-admin

Log Rotation

Configure log rotation:

logging:
  maxSize: "100m"
  maxFiles: "7d"
  compress: true

Backup Configuration

Regularly backup your configuration:

# Backup script
tar -czf mcp-backup-$(date +%Y%m%d).tar.gz \
    .env \
    config/ \
    data/

FAQ

General Questions

Q: What is MCP Server?

A: MCP Server is a bridge between Home Assistant and Language Learning Models, enabling natural language control and automation of your smart home devices.

Q: What are the system requirements?

A: MCP Server requires: - Node.js 16 or higher - Home Assistant instance - 1GB RAM minimum - 1GB disk space

Q: How do I update MCP Server?

A: For Docker installation:

docker compose pull
docker compose up -d

For manual installation:

git pull
bun install
bun run build

Integration Questions

Q: Can I use MCP Server with any Home Assistant instance?

A: Yes, MCP Server works with any Home Assistant instance that has the REST API enabled and a valid long-lived access token.

Q: Does MCP Server support all Home Assistant integrations?

A: MCP Server supports all Home Assistant devices and services that are accessible via the REST API.

Security Questions

Q: Is my Home Assistant token secure?

A: Yes, your Home Assistant token is stored securely and only used for authenticated communication between MCP Server and your Home Assistant instance.

Q: Can I use MCP Server remotely?

A: Yes, but we recommend using a secure connection (HTTPS) and proper authentication when exposing MCP Server to the internet.

Troubleshooting Questions

Q: Why are my device states not updating?

A: Check: 1. Home Assistant connection 2. WebSocket connection status 3. Device availability in Home Assistant 4. Network connectivity

Q: Why are my commands not working?

A: Verify: 1. Command syntax 2. Device availability 3. User permissions 4. Home Assistant API access