---

name: mcp-debugging description: Debug MCP server issues and analyze logs for the Orient. Use this skill when investigating tool failures, API errors, slow operations, or troubleshooting MCP tool behavior. Covers log file locations, JSON log format, correlation IDs for request tracing, common debugging commands, and log rotation configuration.

MCP Server Debugging

Log Files

JSON Log Structure

Copy{
  "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

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

Trace a Request (by correlation ID)

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

Check Tool Calls

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

Check JQL Queries

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

Find Slow Operations (>3s)

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

Watch Logs Real-Time

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

Filter by Service

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

Common Debugging Scenarios

MCP Tool Not Working

1. Check if tool was invoked:

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

2. Check completion status:

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

3. Trace full request using correlation ID

Jira API Issues

Copy# 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

Copy# 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

Copygrep '"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

CopyLOG_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