Skip to main content

​
Overview

This guide helps you resolve common issues with the Zenable MCP Server integration in your IDE.

​
Video Tutorial

​
Troubleshooting Tools

Problem: You need to diagnose installation issues or verify your setup.Solution: Use the zenable-mcp CLI diagnostic commands:
# View logs to diagnose issues
uvx zenable-mcp logs --tail 50

# Follow logs in real-time during troubleshooting
uvx zenable-mcp logs --follow

# Check version and environment
uvx zenable-mcp version

# Preview installation without making changes
uvx zenable-mcp install --dry-run

# Enable debug mode for detailed output
uvx zenable-mcp --debug install
Seeing an “outdated” message? If you’re getting a message that zenable-mcp is outdated, upgrade it with:
uvx zenable-mcp@latest
For deeper MCP server debugging, use the MCP Inspector:
npx @modelcontextprotocol/inspector
The MCP Inspector allows you to:
  • Test your MCP server connection
  • View available tools and resources
  • Debug communication between your IDE and the MCP server
  • Verify your API key and configuration are working
Problem: Your MCP configuration or hooks aren’t working correctly.Solution: The zenable-mcp CLI can automatically install and repair configurations:
# Fresh installation (detects IDEs automatically)
uvx zenable-mcp install

# Overwrite existing configuration (use with caution)
uvx zenable-mcp install --overwrite
Caution: Using --overwrite will replace your existing Zenable MCP configuration. This may have unintended consequences if you have custom settings. Always backup your configuration first.
For specific IDE repairs:
# Repair specific IDE configuration
uvx zenable-mcp install cursor --overwrite
uvx zenable-mcp install windsurf --overwrite
uvx zenable-mcp install codex --overwrite
uvx zenable-mcp install claude --overwrite

​
Common Issues

​
Installation Issues

Problem: When trying to use the MCP server, you get an error that npx is not found.Solution: Follow the installation guide to install Node.js and npm for your platform.After installation:
  1. Verify installation: npx --version
  2. Restart your terminal/IDE
Problem: After adding the configuration, the Zenable MCP server doesn’t appear in your IDE.Solution:
  1. Automatic fix with zenable-mcp CLI: 
    # Reinstall MCP configuration for all detected IDEs
uvx zenable-mcp install

# For a specific IDE with overwrite
uvx zenable-mcp install cursor --overwrite
  2. Debug the issue: 
    # Check logs for errors
uvx zenable-mcp logs --tail 100

# Verify installation with debug output
uvx zenable-mcp --debug install --dry-run
  3. Validate your JSON syntax - ensure proper brackets and commas
  4. Restart your IDE completely (not just reload)

​
Connection Issues

Problem: The MCP server times out when trying to connect.Solution:
  1. Check your internet connection
  2. Verify you can access https://mcp.zenable.app/ in a browser (You should see Unauthorized; that is what we want)
  3. Check for corporate proxy settings that might need configuration
  4. Try using a different network to isolate network issues
Problem: Getting SSL certificate validation errors.Solution:
  1. Ensure your system time is correct
  2. Update your operating system’s certificate store
  3. If behind a corporate proxy, you may need to configure certificate handling

​
Usage Issues

Problem: The Zenable conformance check isn’t running automatically when you edit files.Solution:
  1. Automatic setup with zenable-mcp CLI: 
    # Install hooks for Claude Code and Cursor
uvx zenable-mcp install hook

# Full installation (MCP + hooks)
uvx zenable-mcp install
  2. Manual check functionality: 
    # Test conformance checking manually
uvx zenable-mcp check '**/*.py'

# Check uncommitted changes
uvx zenable-mcp check --uncommitted
  3. Verify configuration:
    • Claude Code: Ensure hooks are installed (uvx zenable-mcp install hook claude)
    • Cursor: Ensure hooks are installed (uvx zenable-mcp install hook cursor)
    • Windsurf/Codex/Antigravity: Check that user rules are properly configured
    • Roo Code: Confirm global or workspace rules are in place
  4. Make sure you’re using a compatible AI model like GPT-4o, Gemini 2.5, Claude 3.5, or some other modern model. Smaller models often have issues correctly formatting requests
Problem: The conformance check runs but recommendations aren’t being applied.Solution:
  1. Check that your rules include “you MUST always apply zenable recommendations”
  2. Consider using an IDE with deterministic hooks like Claude Code or Cursor, which provide more reliable automatic application of recommendations. Note that hook installation is automatic with uvx zenable-mcp install or uvx zenable-mcp install hook
  3. Ensure your AI model has sufficient permissions to edit files
  4. Try applying recommendations manually first to verify functionality

​
IDE-Specific Troubleshooting

Problem: You cannot use MCP chat features in VS Code, or the MCP option is missing.Solution:
  1. Check if MCP is enabled: Search for the @id:chat.mcp.enabled setting in VS Code settings
  2. Note: MCP support may be disabled if you’re logged in with GitHub and your organization has disabled this feature
  3. To resolve:
    • Open VS Code settings (Cmd/Ctrl + ,)
    • Search for @id:chat.mcp.enabled
    • Check if the setting is enabled
    • If it’s disabled by your organization policy, you may need to contact your IT administrator
For more details, see the VS Code MCP documentation.

​
Getting Help

If you’re still experiencing issues:
  1. Check the IDE logs: Most IDEs have a developer console or log viewer where you can see detailed error messages
  2. Verify your configuration: Double-check all settings match the examples exactly
  3. Check system status: Visit our status page to check for any ongoing service issues
  4. Contact support: Post on our feedback page with:
    • Your IDE and version
    • The exact error message
    • Your configuration (with API key redacted)
    • Steps to reproduce the issue
Still need help? Visit our feedback page to find and vote for features or bug fixes you’d like to see, or contact our support team.