Debug MCP Server

Debug MCP

MCP server for debugging distributed systems (AWS CloudWatch Logs, Step Functions, LangSmith, Jira) directly from Claude Code or any MCP client.

Status: ✅ Complete - Single gateway tool exposing 17 debugging tools Context Reduction: ~95% token savings (13K → ~500 tokens) Repository: https://github.com/Coykto/debug_mcp

Quick Start

Installation

Option 1: Using Claude Code CLI (Recommended)

AWS only:

claude mcp add --scope user --transport stdio debug-mcp \
    -- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
    --aws-region us-west-2 \
    --aws-profile your-aws-profile-name

AWS + Jira:

claude mcp add --scope user --transport stdio debug-mcp \
    -- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
    --aws-region us-west-2 \
    --aws-profile your-aws-profile-name \
    --jira-host yourcompany.atlassian.net \
    --jira-email your.email@company.com \
    --jira-project PROJ \
    --jira-token your-api-token

Option 2: Manual configuration in .mcp.json

AWS only:

{
  "mcpServers": {
    "debug-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/Coykto/debug_mcp",
        "debug-mcp",
        "--aws-region", "us-west-2",
        "--aws-profile", "your-aws-profile-name"
      ]
    }
  }
}

AWS + Jira:

{
  "mcpServers": {
    "debug-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/Coykto/debug_mcp",
        "debug-mcp",
        "--aws-region", "us-west-2",
        "--aws-profile", "your-aws-profile-name",
        "--jira-host", "yourcompany.atlassian.net",
        "--jira-email", "your.email@company.com",
        "--jira-project", "PROJ",
        "--jira-token", "your-api-token"
      ]
    }
  }
}

Note: Configuration is passed as CLI arguments to work around a known bug in Claude Code where environment variables aren't reliably passed to MCP servers.

Prerequisites:

• Python 3.11+
• uvx installed (installation guide)
• AWS credentials configured (aws configure)
• For Jira: API token from Atlassian (see Jira Configuration)

How to Use

Debug MCP exposes a single gateway tool called debug() that provides discovery and execution of 17 debugging tools:

Discovery Pattern

Ask Claude to discover available tools:

"What debugging tools are available?"
→ Claude calls: debug(tool="list")

"What CloudWatch tools are available?"
→ Claude calls: debug(tool="list:cloudwatch")

"List all Step Functions tools"
→ Claude calls: debug(tool="list:stepfunctions")

Execution Pattern

Ask Claude natural language questions and it will use the appropriate tool:

CloudWatch Logs:

• "List all Lambda log groups"
• "Search for ERROR in /aws/lambda/my-function from the last hour"
• "Analyze /aws/lambda/my-function logs for patterns"
• "Run a CloudWatch Insights query on my Lambda logs"

Step Functions Debugging:

• "List all my Step Functions state machines"
• "Show me the workflow definition and Lambda functions for state machine X"
• "Show me failed executions for state machine X from the last 3 days"
• "Get execution details including the workflow definition"
• "Find executions where the Match state output contains 'company' and show me the Lambda ARNs"

LangSmith Tracing:

• "List my LangSmith projects in prod environment"
• "Show me errored runs from the last hour in production"
• "Get details for LangSmith run abc-123 in dev"
• "Search for conversations containing a specific error message"

Jira Tickets:

• "Search for bugs in To Do status"
• "Find tickets assigned to me"
• "Get details for ticket PROJ-123"
• "Show me all in-progress stories about authentication"

Claude automatically translates your questions into the appropriate debug() call with the right tool name and arguments.

How It Works

This MCP server uses a Tool Discovery Gateway pattern:

1. Single Tool Interface: Exposes one debug() tool to Claude instead of 17 individual tools
2. ~95% Token Reduction: Reduces context from ~13K tokens to ~500 tokens (tool list only)
3. Category-based Discovery: Tools organized by category (cloudwatch, stepfunctions, langsmith, jira)
4. Direct Implementation: Uses boto3 and SDKs directly (no AWS MCP proxies)

Gateway Architecture

debug(tool="list")                     → List categories
debug(tool="list:cloudwatch")          → List CloudWatch tools
debug(tool="describe_log_groups", ...) → Execute tool

All 17 debugging tools remain available - they're just accessed through the gateway instead of being exposed individually.

Available Tools (via Gateway)

CloudWatch Logs (4 tools)

• describe_log_groups - List CloudWatc