Common Issues & Solutions

Common Issues & Solutions

This guide covers the most frequently encountered issues when using MCP Client Tester, along with step-by-step solutions and prevention strategies.

Installation & Setup Issues

Docker Services Not Starting

Symptoms:

• Services fail to start with docker-compose up
• Health check failures
• Connection refused errors

Common Causes & Solutions:

Port Conflicts

Problem: Ports 80, 443, or other required ports are already in use.

Solution:

# Check which process is using the port
sudo lsof -i :80
sudo lsof -i :443

# Kill the conflicting process or change ports in docker-compose.yml
# Alternative: Use different ports in .env file
PORT_HTTP=8080
PORT_HTTPS=8443

Caddy Network Issues

Problem: External Caddy network doesn’t exist or conflicts.

Solution:

# Check if caddy network exists
docker network ls | grep caddy

# Create the network if it doesn't exist
docker network create caddy

# If there are conflicts, remove and recreate
docker network rm caddy
docker network create caddy

Insufficient Resources

Problem: Docker daemon running out of memory or disk space.

Solution:

# Check Docker system usage
docker system df

# Clean up unused resources
docker system prune -a

# Increase Docker memory limit in Docker Desktop settings
# Or for Linux, check available memory
free -h

Domain Resolution Issues

Symptoms:

• Cannot access https://mcp-tester.local
• DNS resolution failures
• SSL certificate errors

Solutions:

1. Configure Hosts File

   # Linux/macOS: Edit /etc/hosts
   sudo nano /etc/hosts
   
   # Add these lines
   127.0.0.1    mcp-tester.local
   127.0.0.1    api.mcp-tester.local
   127.0.0.1    docs.mcp-tester.local
   127.0.0.1    reports.mcp-tester.local
   
   # Windows: Edit C:\Windows\System32\drivers\etc\hosts (as Administrator)

2. Use Alternative Domain

   # Update .env file
   DOMAIN=localhost
   PUBLIC_DOMAIN=localhost
   
   # Restart services
   docker-compose down && docker-compose up -d

3. Setup Local DNS Server

   # Using dnsmasq on macOS
   brew install dnsmasq
   echo 'address=/.local/127.0.0.1' > /etc/dnsmasq.conf
   sudo brew services start dnsmasq

Connection & Transport Issues

STDIO Transport Problems

Symptoms:

• Client fails to connect via STDIO
• Process spawn errors
• Broken pipe errors

Diagnostic Steps:

# Check if the MCP server process is executable
docker-compose exec backend python -m app.mcp.stdio_server --help

# Test STDIO connection manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | \
  docker-compose exec -T backend python -m app.mcp.stdio_server

# Check container logs
docker-compose logs backend

Common Solutions:

1. Permission Issues

   # Ensure the script is executable
   chmod +x path/to/mcp/server/script
   
   # Check container permissions
   docker-compose exec backend ls -la /app/app/mcp/

2. Path Problems

   # Use absolute paths in client configuration
   {
     "command": "/usr/bin/docker",
     "args": ["compose", "exec", "backend", "python", "-m", "app.mcp.stdio_server"]
   }

3. Environment Variables

   # Ensure required environment variables are set
   docker-compose exec backend env | grep MCP

HTTP Transport Issues

Symptoms:

• HTTP 404/500 errors
• Timeout issues
• CORS problems

Diagnostic Commands:

# Test HTTP endpoint directly
curl -v "https://api.mcp-tester.local/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# Check backend health
curl "https://api.mcp-tester.local/health"

# Test without SSL
curl -k "https://api.mcp-tester.local/mcp" --insecure

Solutions:

1. SSL Certificate Issues

   # For development, accept self-signed certificates
   curl -k "https://api.mcp-tester.local/mcp" --insecure
   
   # Or configure your client to accept self-signed certificates

2. CORS Configuration

   # In backend configuration
   from fastapi.middleware.cors import CORSMiddleware
   
   app.add_middleware(
       CORSMiddleware,
       allow_origins=["*"],  # Configure appropriately for production
       allow_credentials=True,
       allow_methods=["*"],
       allow_headers=["*"],
   )

3. Reverse Proxy Issues

   # Check Caddy logs
   docker logs caddy_container_name
   
   # Test direct backend connection (bypassing proxy)
   curl "http://localhost:8000/health"

WebSocket/SSE Connection Problems

Symptoms:

• WebSocket connection failures
• SSE stream interruptions
• Real-time updates not working

Debugging Steps:

# Test WebSocket connection
wscat -c "wss://api.mcp-tester.local/ws"

# Test SSE endpoint
curl -N "https://api.mcp-tester.local/api/v1/sessions/test-session/events"

# Check browser developer tools for WebSocket errors

Solutions:

1. Proxy Configuration

   # In docker-compose.yml labels
   caddy.@ws.0_header: Connection *Upgrade*
   caddy.@ws.1_header: Upgrade websocket
   caddy.0_reverse_proxy: "@ws {{upstreams 8000}}"

2. Firewall/Network Issues

   # Check if WebSocket ports are accessible
   telnet api.mcp-tester.local 443
   
   # Test from different network location

Protocol & Message Issues

JSON-RPC Format Errors

Symptoms:

• “Invalid Request” errors
• “Parse error” responses
• Message format validation failures

Common Format Issues:

Incorrect Message Format

// ❌ Missing required fields
{
  "method": "tools/list"
}

// ✅ Correct format
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Validation Steps:

# Validate JSON-RPC message format
import json

def validate_jsonrpc(message):
    required_fields = ["jsonrpc", "method"]

    if not isinstance(message, dict):
        return False, "Message must be a JSON object"

    if message.get("jsonrpc") != "2.0":
        return False, "jsonrpc must be '2.0'"

    if "method" not in message:
        return False, "method field is required"

    # For requests, id is required
    if "id" in message and not isinstance(message["id"], (str, int, type(None))):
        return False, "id must be string, number, or null"

    return True, "Valid"

# Test your messages
message = {"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
valid, error = validate_jsonrpc(message)
print(f"Valid: {valid}, Error: {error}")

Method Not Found Errors

Symptoms:

• “Method not found” error responses
• Client calls fail for existing methods

Debugging Steps:

1. List Available Methods

   # Get server capabilities
   curl -X POST "https://api.mcp-tester.local/mcp" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

2. Check Method Names

   # Common method name issues
   correct_methods = [
       "initialize",
       "tools/list",
       "tools/call",
       "resources/list",
       "resources/read",
       "prompts/list",
       "prompts/get"
   ]
   
   # Case-sensitive - "Tools/List" vs "tools/list"
   # Spelling - "tool/list" vs "tools/list"

3. Verify Server Implementation

   # Check if method is actually implemented
   @app.tool()
   def my_tool(param: str) -> str:
       return f"Result: {param}"
   
   # Method name becomes "tools/call" with name="my_tool"

Parameter Validation Errors

Symptoms:

• “Invalid params” errors
• Type validation failures
• Required parameter missing

Common Parameter Issues:

# Tool definition
@app.tool()
def search_data(query: str, limit: int = 10) -> dict:
    """Search for data"""
    return {"results": []}

# ❌ Wrong parameter types
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_data",
    "arguments": {
      "query": 123,        # Should be string
      "limit": "invalid"   # Should be integer
    }
  }
}

# ✅ Correct parameter types
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_data",
    "arguments": {
      "query": "test search",
      "limit": 10
    }
  }
}

Performance Issues

Slow Response Times

Symptoms:

• High latency in tool calls
• Timeouts during operations
• Poor user experience

Diagnostic Steps:

1. Enable Performance Monitoring

   # In session configuration
   {
     "config": {
       "enable_metrics": true,
       "detailed_timing": true,
       "profile_requests": true
     }
   }

2. Check System Resources

   # Monitor container resources
   docker stats
   
   # Check backend logs for performance warnings
   docker-compose logs backend | grep -i "slow\|timeout\|performance"

3. Analyze Session Data

   # Export session performance data
   curl "https://api.mcp-tester.local/api/v1/sessions/{session_id}/export?format=json&include=performance"

Optimization Strategies:

1. Database Optimization

   # Add database indexes
   # Use connection pooling
   # Implement query optimization
   
   # Example: Add async/await for I/O operations
   @app.tool()
   async def search_data(query: str) -> dict:
       async with database.transaction():
           results = await database.fetch_all(
               "SELECT * FROM data WHERE content LIKE :query",
               {"query": f"%{query}%"}
           )
           return {"results": [dict(row) for row in results]}

2. Caching Implementation

   from functools import lru_cache
   import redis
   
   # In-memory caching
   @lru_cache(maxsize=128)
   def expensive_operation(param):
       # Expensive computation
       return result
   
   # Redis caching
   redis_client = redis.Redis(host='redis')
   
   @app.tool()
   async def cached_search(query: str) -> dict:
       cache_key = f"search:{query}"
       cached_result = redis_client.get(cache_key)
   
       if cached_result:
           return json.loads(cached_result)
   
       result = await perform_search(query)
       redis_client.setex(cache_key, 300, json.dumps(result))
       return result

Memory Issues

Symptoms:

• Out of memory errors
• Container restarts
• Performance degradation over time

Solutions:

1. Memory Monitoring

   # Monitor memory usage
   docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}"
   
   # Check for memory leaks
   docker-compose logs backend | grep -i "memory\|oom"

2. Memory Optimization

   # Implement proper cleanup
   @app.tool()
   async def process_large_data(file_path: str) -> dict:
       try:
           # Process data in chunks
           with open(file_path, 'r') as f:
               results = []
               for chunk in read_chunks(f, chunk_size=1024):
                   result = process_chunk(chunk)
                   results.append(result)
                   # Clean up intermediate data
                   del chunk
           return {"processed": len(results)}
       finally:
           # Explicit cleanup
           gc.collect()

Client-Specific Issues

Claude Desktop Integration Problems

Symptoms:

• Claude Desktop doesn’t see MCP server
• Tools not available in conversations
• Connection drops frequently

Troubleshooting:

1. Check Configuration Format

   // ❌ Incorrect configuration
   {
     "mcpServers": {
       "test-server": {
         "command": ["python", "server.py"]  // Should be string
       }
     }
   }
   
   // ✅ Correct configuration
   {
     "mcpServers": {
       "test-server": {
         "command": "python",
         "args": ["server.py"]
       }
     }
   }

2. Verify Server Executable

   # Test server manually
   python server.py
   
   # Check if server responds to initialization
   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python server.py

3. Check Claude Desktop Logs

   • macOS: ~/Library/Logs/Claude/
   • Windows: %APPDATA%\Claude\logs\
   • Look for MCP-related error messages

Custom Client Issues

Symptoms:

• Custom client can’t connect
• Protocol negotiation fails
• Feature detection problems

Debugging Process:

1. Implement Debug Logging

   import logging
   
   logging.basicConfig(level=logging.DEBUG)
   logger = logging.getLogger(__name__)
   
   class DebugMCPClient:
       def send_message(self, message):
           logger.debug(f"Sending: {json.dumps(message)}")
           response = self.transport.send(message)
           logger.debug(f"Received: {json.dumps(response)}")
           return response

2. Test Protocol Compliance

   # Minimal compliant client
   def test_basic_connection():
       # Step 1: Initialize
       init_request = {
           "jsonrpc": "2.0",
           "id": 1,
           "method": "initialize",
           "params": {
               "protocolVersion": "1.0.0",
               "capabilities": {},
               "clientInfo": {
                   "name": "Test Client",
                   "version": "1.0.0"
               }
           }
       }
   
       response = send_request(init_request)
       assert response.get("result") is not None
   
       # Step 2: Test basic functionality
       tools_request = {
           "jsonrpc": "2.0",
           "id": 2,
           "method": "tools/list"
       }
   
       response = send_request(tools_request)
       assert "result" in response

Error Codes Reference

Standard JSON-RPC Errors

Code	Name	Description	Solution
-32700	Parse error	Invalid JSON	Check JSON syntax
-32600	Invalid Request	Invalid JSON-RPC	Verify message format
-32601	Method not found	Unknown method	Check method name spelling
-32602	Invalid params	Invalid parameters	Validate parameter types
-32603	Internal error	Server error	Check server logs

MCP-Specific Errors

Code	Name	Description	Solution
-32000	Server error	MCP server error	Check server implementation
-32001	Tool not found	Unknown tool name	Verify tool is registered
-32002	Resource not found	Invalid resource URI	Check resource path
-32003	Permission denied	Access denied	Verify permissions

Getting Help

When you encounter issues not covered here:

1. Check Logs

   # View all service logs
   docker-compose logs
   
   # View specific service logs
   docker-compose logs backend
   docker-compose logs frontend

2. Enable Debug Mode

   # Set debug environment variables
   export DEBUG=true
   export LOG_LEVEL=DEBUG
   
   docker-compose up -d

3. Export Session Data

   # Get detailed session information
   curl "https://api.mcp-tester.local/api/v1/sessions/{session_id}/export?format=json&include=all" \
     --output debug_session.json

4. Create Minimal Reproduction

   • Isolate the issue to the smallest possible test case
   • Document the exact steps to reproduce
   • Include relevant configuration and error messages

Tip

For complex issues, the MCP Client Tester’s detailed logging and session export features provide comprehensive debugging information that can help identify root causes quickly.

---

Still having issues? Check our specific troubleshooting guides for Connection Problems, Protocol Errors, or Performance Issues.