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:
- Check Service Status: Monitor LookC status page for known issues
- Review API Limits: Verify your account's rate limits and quotas
- 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.
