Claude-skill-registry-data mcp-debugging

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.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry-data

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry-data "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/mcp-debugging" ~/.claude/skills/majiayu000-claude-skill-registry-data-mcp-debugging && rm -rf "$T"

manifest: data/mcp-debugging/SKILL.md

source content

MCP Server Debugging

Log Files

File	Purpose
`logs/mcp-debug.log`	All debug logs (JSON format)
`logs/mcp-error.log`	Error-only logs

JSON Log Structure

{
  "timestamp": "2024-12-09 14:30:45.123",
  "level": "INFO",
  "message": "Tool completed: ai_first_health_check",
  "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, slack-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 Tool Arguments

tail -100 logs/mcp-debug.log | jq '{tool: .tool, args: .args}' | head -20

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

Check if tool was invoked:

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

Check completion status:

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

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

Variable	Default	Description
`LOG_MAX_SIZE`	`10m`	Max size before rotation
`LOG_MAX_DAYS`	`14d`	Days to keep debug logs

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

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