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:```bash
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:```bash
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:```json
{
"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:```json
{
"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 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 resources
- list_step_function_executions - List executions with filtering
- get_step_function_execution_details - Get full execution details with state inputs/outputs
- search_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 data
- search_step_function_executions - See definitions with filtered execution results
LangSmith (6 tools)
Tracing & Debugging:
- list_langsmith_projects - List available LangSmith projects
- list_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 text
- search_run_content - Semantic search within a stored run's content
- get_run_field - Get a specific field from a stored run
Multi-Environment Support:
Each LangSmith tool requires an environment parameter:
- prod - Uses PRODUCTION/env/vars from AWS Secrets Manager
- dev - Uses DEV/env/vars from AWS Secrets Manager
- local - Loads from .env file using python-dotenv
Credentials in Secrets Manager:
Your AWS Secrets Manager secret should contain:
- LANGCHAIN_API_KEY - Your LangSmith API key
- LANGCHAIN_PROJECT - Default project name (optional)
Local Development (.env file):```env
LANGCHAIN_API_KEY=ls_your_api_key_here
LANGCHAIN_PROJECT=your-project-name
> **Note**: LangSmith integration currently requires AWS Secrets Manager for `prod`/`dev` environments (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 search
- `get_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):```bash
# 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:```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:```bash
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)```bash
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**```json
{
"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:```bash
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., `PROJ` in `PROJ-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-region` and `--aws-profile` CLI 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```bash
# 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:
1. They update --aws-profile with their own profile name
2. Optionally adjust --aws-region if different
3. 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:
1. Fork the repository
2. Create a feature branch
3. Make your changes (see Adding New Tools in CLAUDE.md)
4. Submit a PR
License
MIT License - See LICENSE file
