mcp-debugging

MCP Server Debugging

Log Files

JSON Log Structure

{
  "timestamp": "2024-12-09 14:30:45.123",
  "level": "INFO",
  "message": "Tool completed: ai_first_get_all_issues",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "service": "mcp-server",
  "operation": "tool_call",
  "durationMs": 1234,
  "meta": { ... }
}

Key Fields:

• correlationId - UUID linking all logs for a single tool invocation
• service - Component (mcp-server, jira-service, slides-service, config)
• durationMs - Operation duration in milliseconds
• meta - Context (JQL queries, issue counts, API responses)

Quick Debugging Commands

Check Recent Errors

tail -20 logs/mcp-error.log | jq .

Trace a Request (by correlation ID)

grep "550e8400" logs/mcp-debug.log | jq .

Check Tool Calls

tail -100 logs/mcp-debug.log | grep "tool_call" | jq '{tool: .tool, status: .status}'

Check JQL Queries

grep '"jql"' logs/mcp-debug.log | jq '.meta.jql // .jql' | sort -u

Find Slow Operations (>3s)

grep durationMs logs/mcp-debug.log | jq 'select(.durationMs > 3000)'

Watch Logs Real-Time

tail -f logs/mcp-debug.log | jq .

Filter by Service

tail -f logs/mcp-debug.log | grep '"service":"jira"' | jq .

Common Debugging Scenarios

MCP Tool Not Working

1. Check if tool was invoked:

   grep "Tool invoked: TOOL_NAME" logs/mcp-debug.log | tail -5
   

2. Check completion status:

   grep "TOOL_NAME" logs/mcp-debug.log | grep -E '"status":"(success|error)"' | tail -5 | jq .
   

3. Trace full request using correlation ID

Jira API Issues

# Check Jira errors
grep '"service":"jira' logs/mcp-debug.log | grep '"level":"ERROR"' | jq .

# See JQL queries
grep '"service":"jira' logs/mcp-debug.log | jq 'select(.meta.jql) | {operation: .operation, jql: .meta.jql}'

Google Slides API Issues

# Check initialization
grep '"service":"slides' logs/mcp-debug.log | grep "initialize" | jq .

# Check operations
grep '"service":"slides' logs/mcp-debug.log | jq '{operation: .operation, slideId: .meta.slideId, status: .status}'

Config Loading Issues

grep '"service":"config"' logs/mcp-debug.log | jq .

Log Level Configuration

Set via LOG_LEVEL environment variable:

• error - Only errors
• warn - Errors and warnings
• info - Normal operation (default)
• debug - Verbose debugging

LOG_LEVEL=debug npm run start

Log Rotation

Log files are named: mcp-debug-YYYY-MM-DD.log Old logs are compressed: mcp-debug-YYYY-MM-DD.log.gz

Sensitive Data

Logs automatically redact:

• API tokens
• Passwords
• Secrets
• Authorization headers

[REDACTED] in logs is intentional security behavior.

Debugging Tips

1. Start with correlation ID - Links all related log entries
2. Check timestamps - Look for unusual gaps (hanging operations)
3. Compare durations - Sudden increases indicate API issues
4. Look at meta field - Detailed context (issue counts, JQL, responses)
5. Use jq for filtering - JSON format makes extraction easy
6. Check stderr during startup - Human-readable logs for immediate visibility