Debugging & Error Handling

Comprehensive guide to troubleshooting issues and handling errors when integrating with the LookC MCP server.


Common Issues

The most frequently encountered issues when working with the LookC MCP server and their solutions.

Authentication Problems

401 Unauthorized

Invalid or missing API key in the Authorization header.

403 Forbidden

API key lacks required permissions for the requested operation.

Solutions:

Authentication debugging

# Verify your API key works
curl -X POST https://api.lookc.io/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# Expected response should include available tools

Connection Issues

  • Name
    Network Timeouts
    Type
    error
    Description

    Symptoms: Requests hang or timeout after 30+ seconds Causes: Network connectivity issues, firewall blocking HTTPS traffic Solution: Check network connectivity, verify HTTPS access to api.lookc.io

  • Name
    SSL Certificate Errors
    Type
    error
    Description

    Symptoms: SSL verification failures or certificate errors Causes: Corporate firewalls, outdated certificate stores Solution: Update certificates or configure proxy settings

  • Name
    DNS Resolution Failures
    Type
    error
    Description

    Symptoms: "Host not found" or DNS resolution errors Causes: DNS configuration issues, network restrictions Solution: Test DNS resolution: nslookup api.lookc.io

Tool Parameter Issues

Parameter validation

// ❌ Incorrect - missing required org_id
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_employee_list",
    "arguments": {
      "title_regex": "engineer"
    }
  }
}

// ✅ Correct - includes required org_id
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_employee_list",
    "arguments": {
      "org_id": "550e8400-e29b-41d4-a716-446655440000",
      "title_regex": "engineer"
    }
  }
}

Error Codes

Complete reference for LookC MCP server error codes and their meanings.

HTTP Status Codes

  • Name
    200 OK
    Type
    success
    Description

    Request successful, response contains valid data

  • Name
    400 Bad Request
    Type
    error
    Description

    Invalid JSON-RPC format or malformed request parameters

  • Name
    401 Unauthorized
    Type
    error
    Description

    Missing or invalid API key in Authorization header

  • Name
    403 Forbidden
    Type
    error
    Description

    API key lacks required permissions for the requested operation

  • Name
    429 Too Many Requests
    Type
    error
    Description

    Rate limit exceeded, implement exponential backoff

  • Name
    500 Internal Server Error
    Type
    error
    Description

    Server-side error, retry with exponential backoff

  • Name
    503 Service Unavailable
    Type
    error
    Description

    Temporary service outage, retry after delay

JSON-RPC Error Codes

  • Name
    -32700 Parse Error
    Type
    error
    Description

    Invalid JSON format in request body

  • Name
    -32600 Invalid Request
    Type
    error
    Description

    Missing required JSON-RPC fields (jsonrpc, method, id)

  • Name
    -32601 Method Not Found
    Type
    error
    Description

    Unknown method name (e.g., typo in "tools/call")

  • Name
    -32602 Invalid Params
    Type
    error
    Description

    Invalid tool parameters or missing required fields

  • Name
    -32603 Internal Error
    Type
    error
    Description

    Server-side processing error

LookC-Specific Error Codes

  • Name
    INVALID_TOKEN
    Type
    error
    Description

    API token is malformed or expired

  • Name
    ORG_NOT_FOUND
    Type
    error
    Description

    Organization ID or LinkedIn URL not found in database

  • Name
    RATE_LIMITED
    Type
    error
    Description

    Request rate limit exceeded for your API key

  • Name
    INVALID_PARAMS
    Type
    error
    Description

    Tool-specific parameter validation failed

  • Name
    QUOTA_EXCEEDED
    Type
    error
    Description

    Monthly API quota limit reached

Debugging Tools

Essential tools and techniques for debugging LookC MCP integration issues.

MCP Inspector

The MCP Inspector is invaluable for testing and debugging MCP server connections:

MCP Inspector usage

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Connect to LookC MCP server
mcp-inspector https://api.lookc.io/mcp \
  --auth-header "Authorization: Bearer YOUR_API_KEY"

HTTP Debugging Tools

HTTP debugging

# Debug HTTP requests with verbose output
curl -v -X POST https://api.lookc.io/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# The -v flag shows:
# - DNS resolution
# - SSL handshake
# - Request headers
# - Response headers
# - Timing information

Error Handling Patterns

Robust error handling

import time
import random
from typing import Optional, Dict, Any

class LookCMCPClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.endpoint = "https://api.lookc.io/mcp"
        
    async def call_tool_with_retry(
        self, 
        tool_name: str, 
        arguments: Dict[str, Any],
        max_retries: int = 3
    ) -> Optional[Dict[str, Any]]:
        """Call LookC tool with comprehensive error handling."""
        
        for attempt in range(max_retries):
            try:
                result = await self._make_request(tool_name, arguments)
                return result
                
            except requests.exceptions.Timeout:
                if attempt < max_retries - 1:
                    wait_time = (2 ** attempt) + random.uniform(0, 1)
                    print(f"⏱️ Timeout on attempt {attempt + 1}, retrying in {wait_time:.1f}s")
                    await asyncio.sleep(wait_time)
                else:
                    print("❌ All retry attempts failed due to timeout")
                    raise
                    
            except requests.exceptions.HTTPError as e:
                if e.response.status_code == 429:  # Rate limited
                    retry_after = int(e.response.headers.get('Retry-After', 60))
                    print(f"🚦 Rate limited, waiting {retry_after}s")
                    await asyncio.sleep(retry_after)
                elif e.response.status_code in [500, 502, 503, 504]:  # Server errors
                    if attempt < max_retries - 1:
                        wait_time = (2 ** attempt) + random.uniform(0, 1)
                        print(f"🔧 Server error {e.response.status_code}, retrying in {wait_time:.1f}s")
                        await asyncio.sleep(wait_time)
                    else:
                        print(f"❌ Server error {e.response.status_code} persists after retries")
                        raise
                else:
                    print(f"❌ HTTP error {e.response.status_code}: {e.response.text}")
                    raise
                    
            except Exception as e:
                print(f"❌ Unexpected error: {e}")
                if attempt == max_retries - 1:
                    raise
                await asyncio.sleep(1)
        
        return None

Best Practices

Proven strategies for reliable LookC MCP integration.

Monitoring and Alerting

Request Monitoring

Track request success rates, response times, and error patterns to identify issues early.

Rate Limit Awareness

Implement exponential backoff and respect rate limit headers to avoid throttling.

Development vs Production

Environment-specific handling

import os
from dataclasses import dataclass

@dataclass
class LookCConfig:
    api_key: str
    endpoint: str = "https://api.lookc.io/mcp"
    timeout: int = 30
    max_retries: int = 3
    debug_mode: bool = False
    
    @classmethod
    def from_environment(cls):
        return cls(
            api_key=os.getenv('LOOKC_API_KEY'),
            endpoint=os.getenv('LOOKC_ENDPOINT', 'https://api.lookc.io/mcp'),
            timeout=int(os.getenv('LOOKC_TIMEOUT', '30')),
            max_retries=int(os.getenv('LOOKC_MAX_RETRIES', '3')),
            debug_mode=os.getenv('LOOKC_DEBUG', 'false').lower() == 'true'
        )

# Development configuration
dev_config = LookCConfig(
    api_key="dev_api_key",
    timeout=60,  # Longer timeout for debugging
    max_retries=1,  # Fail fast in development
    debug_mode=True
)

# Production configuration
prod_config = LookCConfig(
    api_key="prod_api_key",
    timeout=30,
    max_retries=3,
    debug_mode=False
)

Getting Help

If you continue to experience issues after following this debugging guide:

  1. Check Service Status: Monitor LookC status page for known issues
  2. Review API Limits: Verify your account's rate limits and quotas
  3. Contact Support: Reach out to your LookC account manager with:
    • Error messages and response codes
    • Request/response examples
    • Your API key (last 4 characters only)
    • Timestamp of the issue

For additional troubleshooting, see our Getting Started guide for basic setup verification.

Was this page helpful?