Skip to main content
The hud debug command validates MCP environments through 5 progressive phases.

​
Synopsis

hud debug [IMAGE|DIRECTORY] [OPTIONS] [DOCKER_ARGS...]
hud debug --config PATH
hud debug --cursor SERVER_NAME

​
Options

OptionDescriptionDefault
--config, -cJSON config file with MCP configuration-
--cursorDebug a Cursor MCP server-
--build, -bBuild image before debugging (directory mode)false
--max-phase, -pMaximum debug phase (1-5)5

​
Debug Phases

​
Phase 1: Container Startup

🚀 Phase 1: Container startup
✓ Container started successfully
✓ Received output on stderr
Checks: Process starts, outputs to stderr, doesn’t exit

​
Phase 2: MCP Initialization

🔗 Phase 2: MCP initialization
✓ Received valid initialize response
✓ Protocol version: 1.0
Checks: JSON-RPC communication, protocol compatibility

​
Phase 3: Tool Discovery

🔧 Phase 3: Tool discovery
✓ Found 8 tools:
  • setup_board - Initialize game board
  • move - Move in direction
Checks: Tools registered, valid schemas

​
Phase 4: Tool Execution

🧪 Phase 4: Tool testing
→ Testing tool: setup_board
✓ Tool executed successfully
Checks: Tools callable, return valid responses

​
Phase 5: Readiness Check

✅ Phase 5: Readiness check
✓ Ready for agent interaction
Checks: Overall health, state persistence
Use hud dev for hot-reload development after debug passes to speed up iteration.

​
Examples

​
Docker Image

# Basic
hud debug my-server:latest

# With environment variables (Docker args after image)
hud debug my-server:latest -e DEBUG=true -e LOG_LEVEL=debug

# Stop at phase 3
hud debug my-server:latest --max-phase 3

​
Directory Mode

# Build then debug from a directory containing a Dockerfile and pyproject.toml
hud debug . --build

​
Common Issues

​
Phase 1 Failures

  • Container exits: Check CMD/ENTRYPOINT
  • No stderr: Route logs to stderr
  • Permission denied: Check file permissions

​
Phase 2 Failures

  • Invalid JSON: Only JSON-RPC on stdout
  • Timeout: Check for blocking operations

​
Phase 3 Failures

  • No tools: Check @server.tool() decorators
  • Invalid schema: Add type hints and docstrings

​
Advanced Usage

​
Incremental Debugging

for phase in 1 2 3 4 5; do
  echo "Testing phase $phase..."
  hud debug my-env:latest --max-phase $phase || break
done

​
Parallel Testing

# Test multiple environments
images=("env1:latest" "env2:latest")
for image in "${images[@]}"; do
  hud debug "$image" > "debug_${image//:/}.log" 2>&1 &
done
wait

​
Best Practices

  1. Start with phase 1 and work up
  2. Use --max-phase for incremental debugging
  3. Check stderr output first
  4. Keep tools simple for easier debugging
  5. Add health check tools
If debug passes, agents should work reliably with your environment.

​
Next Step

Analyze Command

Explore environment capabilities after debugging
⌘I