MCP Allowlist Configuration Guide

Configure which Debugssy tools your AI can use automatically without asking for permission each time

This guide helps you set up allowlists for your MCP client (Claude Desktop, Cursor, Copilot) to streamline your debugging workflow while maintaining security.

📋 Table of Contents

• Quick Start
• How It Works
• Configuration Examples
• Tool Reference
• Troubleshooting
• Security Best Practices

⚡ Quick Start

Too long; didn't read? Copy one of these configs:

🟢 Safest (Recommended for most users)

Uses: assisted mode (default) + read-only tools only

{
  "mcpServers": {
    "debugssy": {
      "url": "http://localhost:3000/mcp",
      "allowlist": [
        "debugssy:get_debug_state",
        "debugssy:get_variables",
        "debugssy:get_call_stack",
        "debugssy:get_console_output",
        "debugssy:list_breakpoints"
      ]
    }
  }
}

✅ You control debugging (F5, F10, F11 in VS Code)
✅ AI can analyze bugs
✅ AI can inspect variables
✅ AI can trace execution
❌ AI cannot set breakpoints or modify anything

🔄 How It Works

Automation Modes (VS Code Setting)

Debugssy has 2 automation modes set via debugssy.automationLevel:

Why this matters: The AI only sees tools it can use, preventing confusing error messages.

Allowlist Levels (MCP Client Configuration)

Within each automation mode, you can further restrict which tools the AI can use without asking permission via allowlists. Below are 3 common configurations:

⚙️ Configuration Examples

Choose the configuration that matches your workflow and AI client:

🟢 Level 1: Read-Only Tools (Safest)

Automation mode: assisted (default, no change needed)
Allowlist: Read-only inspection tools only
For: Code review, understanding bugs, learning
AI can: Inspect state, analyze execution
AI cannot: Set breakpoints, modify anything, control execution

{
  "mcpServers": {
    "debugssy": {
      "url": "http://localhost:3000/mcp",
      "allowlist": [
        "debugssy:get_debug_state",
        "debugssy:get_variables",
        "debugssy:get_call_stack",
        "debugssy:get_console_output",
        "debugssy:list_breakpoints"
      ]
    }
  }
}

{
  "mcpServers": {
    "debugssy": {
      "url": "http://localhost:3000/mcp",
      "allowlist": [
        "debugssy:get_debug_state",
        "debugssy:get_variables",
        "debugssy:get_call_stack",
        "debugssy:get_console_output",
        "debugssy:list_breakpoints"
      ]
    }
  }
}

{
  "github.copilot.chat.mcp.servers": {
    "debugssy": {
      "url": "http://localhost:3000/mcp",
      "allowlist": [
        "debugssy:get_debug_state",
        "debugssy:get_variables",
        "debugssy:get_call_stack",
        "debugssy:get_console_output",
        "debugssy:list_breakpoints"
      ]
    }
  }
}

🔵 Level 2: Assisted Mode with Breakpoints (Recommended)

Automation mode: assisted (default, no change needed)
Allowlist: Read-only + breakpoint management + expression evaluation
For: Interactive debugging, guided workflows
AI can: Everything from Level 1 + set breakpoints + evaluate expressions
You control: Start/stop debugging, step operations via VS Code UI

{
  "mcpServers": {
    "debugssy": {
      "url": "http://localhost:3000/mcp",
      "allowlist": [
        "debugssy:get_debug_state",
        "debugssy:get_variables",
        "debugssy:get_call_stack",
        "debugssy:get_threads",
        "debugssy:get_console_output",
        "debugssy:list_breakpoints",
        "debugssy:set_breakpoint",
        "debugssy:remove_breakpoint",
        "debugssy:evaluate_expression"
      ]
    }
  }
}

🔴 Level 3: Full Automation (Advanced)

Automation mode: full ⚠️ Must set "debugssy.automationLevel": "full" in VS Code settings
Allowlist: All tools including execution control
For: Automated debugging, batch processing, experienced users
AI can: Complete control including starting/stopping sessions, continue, step operations
You control: Nothing (AI drives everything)

⚠️ Only use in trusted environments

{
  "mcpServers": {
    "debugssy": {
      "url": "http://localhost:3000/mcp",
      "allowlist": [
        "debugssy:get_debug_state",
        "debugssy:get_variables",
        "debugssy:get_call_stack",
        "debugssy:get_threads",
        "debugssy:get_console_output",
        "debugssy:list_breakpoints",
        "debugssy:wait_for_breakpoint",
        "debugssy:start_debugging",
        "debugssy:stop_debugging",
        "debugssy:set_breakpoint",
        "debugssy:remove_breakpoint",
        "debugssy:continue",
        "debugssy:pause",
        "debugssy:restart",
        "debugssy:evaluate_expression"
      ]
    }
  }
}

📚 Tool Reference

All Debugssy tools organized by category and safety level:

🟢 Read-Only Tools (Safest)

Why safe: Cannot modify code, change execution, or execute expressions. Read-only access to what's visible in VS Code debugger UI.

🟡 Breakpoint Management Tools

Why generally safe: Only affects debugging, not your actual code. Easy to undo manually via VS Code UI.

🟠 Code Execution Tools

Safety: Expressions are validated for side effects. Safe operations (variable access, arithmetic) run automatically. Dangerous operations (function calls, assignments) require your approval via elicitation.

Expression Validation Levels

Configure how strictly expressions are validated via debugssy.expressionValidationLevel:

Risk Levels Explained:

Example configuration:

{
  "debugssy.expressionValidationLevel": "moderate"
}

Learn more: See EXPRESSION_VALIDATION_GUIDE.md

🔵 Execution Control Tools (Mode-Aware)

Behavior changes based on automation mode:

🔴 Full Automation Only Tools

Why restricted: These tools give AI complete control over debugging. Only visible when automationLevel is set to "full".

🛡️ Security Best Practices

✅ Do's

• ✅ Start with Level 1 (read-only) and add tools as needed
• ✅ Use assisted mode by default - You maintain control
• ✅ Trust the built-in validation - Expression validator protects against unsafe code
• ✅ Test with simple queries first - "What's the value of x?"
• ✅ Review allowlist periodically - Remove unused tools

❌ Don'ts

• ❌ Don't allowlist all tools blindly - Only add what you need
• ❌ Don't use full automation for production - Too risky
• ❌ Don't disable expression validation - Keep expressionValidationLevel at moderate
• ❌ Don't expose remote access - Server is localhost-only by design

🔒 Additional Security Layers

Debugssy has multiple security layers regardless of allowlist:

Learn more: See MCP_COMPLIANCE.md for complete security details

🔧 Troubleshooting

Tools Not Working?

curl http://localhost:3000/health

{
  "status": "ok",
  "server": "debugssy-mcp",
  "version": "1.2.0",
  "transportInitialized": true
}

// In VS Code settings.json
"debugssy.mcp.port": 3000  // Should match your MCP client config

// In VS Code settings.json
"debugssy.automationLevel": "assisted"  // or "full"

{
  "allowlist": ["debugssy:get_debug_state"]
}

// In VS Code settings.json
"debugssy.expressionValidationLevel": "moderate"  // strict, moderate, permissive, or disabled

🎓 Quick Decision Guide

Not sure which configuration to use? Answer these questions:

1. Choose Your Automation Mode (VS Code Setting)

2. Choose Your Allowlist Level (MCP Client Config)

What's your goal?

• Just understand bugs → Level 1 (Read-only tools only)
• Interactive debugging → Level 2 (Add breakpoints + expressions)
• Fully automated sessions → Level 3 (Requires full mode + all tools)

How much control do you want?

• Full control (you click buttons) → Level 1 or 2 with assisted mode
• Let AI drive → Level 3 with full mode

Is this production code?

• Yes → Level 1 only (safest, read-only)
• No → Any level based on your comfort

How much do you trust your AI?

• Still learning → Level 1 (read-only)
• Trust for guided help → Level 2 (breakpoints allowed)
• Complete trust → Level 3 (full automation)

3. Choose Your Expression Validation Level

In VS Code settings (debugssy.expressionValidationLevel):

• Maximum security, don't mind approvals → strict
• Balanced (recommended) → moderate ⭐
• Experienced user, minimal interruption → permissive
• Fully trusted environment only → disabled ⚠️

📚 Additional Resources

• README.md - Complete tool documentation and API reference
• MCP_COMPLIANCE.md - Security implementation details
• EXPRESSION_VALIDATION_GUIDE.md - Expression safety guide
• Model Context Protocol Specification - Official MCP docs

💬 Need Help?

• Issues or bugs: Open an issue
• Questions: Check README.md FAQ
• Security concerns: See MCP_COMPLIANCE.md