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+
uvxinstalled (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:
- Single Tool Interface: Exposes one
debug()tool to Claude instead of 17 individual tools - ~95% Token Reduction: Reduces context from ~13K tokens to ~500 tokens (tool list only)
- Category-based Discovery: Tools organized by category (cloudwatch, stepfunctions, langsmith, jira)
- 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 CloudWatch log groupsanalyze_log_group- Analyze logs for anomalies and patternsexecute_log_insights_query- Run CloudWatch Insights queriesget_logs_insight_query_results- Get query results
Step Functions (5 tools)
Debugging:
list_state_machines- List all state machines (get ARNs)get_state_machine_definition- Get ASL definition with extracted Lambda ARNs and resourceslist_step_function_executions- List executions with filteringget_step_function_execution_details- Get full execution details with state inputs/outputssearch_step_function_executions- Advanced search with state/input/output pattern matching
Definition & Resources:
The get_state_machine_definition tool extracts:
- Full Amazon States Language (ASL) workflow definition
- Lambda function ARNs used in the workflow
- Other resources (SNS topics, SQS queues, DynamoDB tables, nested state machines)
- IAM role, logging, and tracing configuration
You can also include the definition with execution details using include_definition=True in:
get_step_function_execution_details- See the workflow definition alongside execution datasearch_step_function_executions- See definitions with filtered execution results
LangSmith (6 tools)
Tracing & Debugging:
list_langsmith_projects- List available LangSmith projectslist_langsmith_runs- List runs/traces with filtering (type, errors, time range)get_langsmith_run_details- Get full run details with inputs/outputs and child runs (stores in memory)search_langsmith_runs- Search for conversations containing specific textsearch_run_content- Semantic search within a stored run's contentget_run_field- Get a specific field from a stored run
Multi-Environment Support:
Each LangSmith tool requires an environment parameter:
prod- UsesPRODUCTION/env/varsfrom AWS Secrets Managerdev- UsesDEV/env/varsfrom AWS Secrets Managerlocal- Loads from.envfile using python-dotenv
Credentials in Secrets Manager: Your AWS Secrets Manager secret should contain:
LANGCHAIN_API_KEY- Your LangSmith API keyLANGCHAIN_PROJECT- Default project name (optional)
Local Development (.env file):
LANGCHAIN_API_KEY=ls_your_api_key_here
LANGCHAIN_PROJECT=your-project-name
Note: LangSmith integration currently requires AWS Secrets Manager for
prod/devenvironments (this is how our team stores credentials). If you'd like to use LangSmith with direct CLI token arguments (similar to Jira), PRs are welcome!
Jira (2 tools)
search_jira_tickets- Search tickets with filters (type, status, assignee) and text searchget_jira_ticket- Get full ticket details including linked issues, attachments, subtasks, and Epic children
Returned fields for get_jira_ticket:
- Basic: key, summary, description, status, issue_type, priority, assignee, reporter, labels, created, updated
- Relationships: linked_issues, parent (for subtasks), subtasks, epic_children (for Epics)
- Attachments: list of filenames
Configuration
AWS Authentication
Pass AWS credentials as CLI arguments (recommended to work around Claude Code env var bug):
# Using Claude Code CLI
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-profile-name
Or in .mcp.json:
"args": [
"--from", "git+https://github.com/Coykto/debug_mcp",
"debug-mcp",
"--aws-region", "us-west-2",
"--aws-profile", "your-profile-name"
]
Alternative: Set environment variables before launching Claude Code:
export AWS_REGION=us-west-2
export AWS_PROFILE=your-profile-name
# Then launch Claude Code
Jira Configuration
Jira integration allows you to search tickets and get full ticket details directly from Claude Code.
Step 1: Create a Jira API Token
- Go to Atlassian API Token Management
- Click Create API token
- Give it a descriptive label (e.g., "Debug MCP")
- Copy the generated token (you won't see it again)
Step 2: Gather Your Jira Details
You'll need:
- Host: Your Jira Cloud hostname (e.g.,
yourcompany.atlassian.net) - Email: The email address associated with your Atlassian account
- Project: The project key for your default project (e.g.,
PROJ,DEV,CORE) - Token: The API token from Step 1
Step 3: Configure Debug MCP
Option A: Claude Code CLI (Recommended)
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-profile-name \
--jira-host yourcompany.atlassian.net \
--jira-email your.email@company.com \
--jira-project PROJ \
--jira-token your-api-token
Option B: Manual .mcp.json Configuration
{
"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-profile-name",
"--jira-host", "yourcompany.atlassian.net",
"--jira-email", "your.email@company.com",
"--jira-project", "PROJ",
"--jira-token", "your-api-token"
]
}
}
}
Option C: Use Environment Variable for Token
If you prefer not to store the token in your config, set JIRA_API_TOKEN as an environment variable before launching Claude Code:
export JIRA_API_TOKEN=your-api-token
Then omit --jira-token from the CLI args (other Jira args are still required).
Configuration Reference
| Source | Name | Required | Description |
|---|---|---|---|
| CLI arg | --jira-host | Yes | Jira Cloud hostname (e.g., company.atlassian.net) |
| CLI arg | --jira-email | Yes | Atlassian account email |
| CLI arg | --jira-project | Yes | Default Jira project key (e.g., PROJ) |
| CLI arg | --jira-token | Yes* | Jira API token |
| Env var | JIRA_API_TOKEN | Yes* | Alternative to --jira-token CLI arg |
*Either --jira-token or JIRA_API_TOKEN is required.
Jira Troubleshooting
"Jira credentials not configured" error:
- Verify all required args are provided:
--jira-host,--jira-email,--jira-project, and token - Check that your API token is valid at Atlassian API Tokens
"401 Unauthorized" error:
- Your API token may have expired - create a new one
- Verify the email matches your Atlassian account exactly
"Project not found" error:
- Check the project key (not name) - it's the prefix in ticket IDs (e.g.,
PROJinPROJ-123) - Ensure your account has access to the project
Troubleshooting
Server won't start
- Check AWS credentials:
aws sts get-caller-identity --profile YOUR_PROFILE - Verify uvx is installed:
uvx --version - Check Claude Code MCP logs in settings
Wrong AWS region/account
- Update
--aws-regionand--aws-profileCLI arguments - Make sure the profile exists in
~/.aws/credentials - Verify the region is correct:
aws configure get region --profile YOUR_PROFILE
Environment variables not working
Due to a known bug in Claude Code, environment variables in the MCP env block aren't reliably passed to servers. Use CLI arguments instead (see installation examples above).
Development
Local Development
# Install dependencies
uv sync
# Run the server locally
uv run debug-mcp --aws-region us-west-2 --aws-profile your-profile
# Test
uv run pytest
Architecture
The server uses a Tool Discovery Gateway pattern with direct boto3/SDK implementations:
Gateway Layer (src/debug_mcp/server.py):
- Single
debug()tool exposed to Claude - Handles discovery (
tool="list",tool="list:cloudwatch") - Routes execution to registered tools
- Validates arguments with Pydantic models
Registry System (src/debug_mcp/registry.py):
- Central registry for all tools with schemas
- Category-based organization
@debug_tool()decorator for registration- Validation and execution routing
Tool Implementations:
- CloudWatch (
cloudwatch_logs.py+cloudwatch_registry.py): boto3 CloudWatch Logs client - Step Functions (
stepfunctions.py+stepfunctions_registry.py): boto3 Step Functions client - LangSmith (
langsmith.py+langsmith_registry.py): LangSmith SDK with multi-environment support - Jira (
jira.py+jira_registry.py): Jira SDK with lazy client initialization
Each *_registry.py file registers tools using the @debug_tool() decorator with schemas and handlers.
Team Sharing
Share with your team:
- They update
--aws-profilewith their own profile name - Optionally adjust
--aws-regionif different - All 17 debugging tools are available through the single
debug()gateway - no tool filtering needed
Contributing
Contributions are welcome! Some areas where PRs would be appreciated:
- LangSmith CLI token support: Currently LangSmith credentials are loaded from AWS Secrets Manager (for
prod/dev) or.envfiles (forlocal). Adding--langsmith-api-keyCLI argument support (similar to Jira) would make setup easier for teams not using Secrets Manager. - Additional debugging tools: New tools for other AWS services (ECS, Lambda logs, X-Ray traces)
- Bug fixes and improvements: Error handling, documentation, tests
To contribute:
- Fork the repository
- Create a feature branch
- Make your changes (see Adding New Tools in CLAUDE.md)
- Submit a PR
License
MIT License - See LICENSE file