Overview
This guide helps you resolve common issues with the Zenable MCP Server integration in your IDE.Video Tutorial
Troubleshooting Tools
Using the zenable-mcp CLI for Diagnostics
Using the zenable-mcp CLI for Diagnostics
Problem: You need to diagnose installation issues or verify your setup.Solution:
Use the zenable-mcp CLI diagnostic commands:For deeper MCP server debugging, use the MCP Inspector:The MCP Inspector allows you to:
Seeing an “outdated” message? If you’re getting a message that zenable-mcp is outdated, upgrade it with:
- 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
Quick Setup and Repair
Quick Setup and Repair
Problem: Your MCP configuration or hooks aren’t working correctly.Solution:
The zenable-mcp CLI can automatically install and repair configurations:For specific IDE repairs:
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.Common Issues
Installation Issues
npx Command Not Found
npx Command Not Found
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:- Verify installation:
npx --version - Restart your terminal/IDE
MCP Server Not Showing Up in IDE
MCP Server Not Showing Up in IDE
Problem: After adding the configuration, the Zenable MCP server doesn’t appear in your IDE.Solution:
-
Automatic fix with zenable-mcp CLI:
-
Debug the issue:
- Validate your JSON syntax - ensure proper brackets and commas
- Restart your IDE completely (not just reload)
Connection Issues
Connection Timeout
Connection Timeout
Problem: The MCP server times out when trying to connect.Solution:
- Check your internet connection
- Verify you can access
https://mcp.www.zenable.app/in a browser (You should seeUnauthorized; that is what we want) - Check for corporate proxy settings that might need configuration
- Try using a different network to isolate network issues
SSL/TLS Certificate Errors
SSL/TLS Certificate Errors
Problem: Getting SSL certificate validation errors.Solution:
- Ensure your system time is correct
- Update your operating system’s certificate store
- If behind a corporate proxy, you may need to configure certificate handling
Usage Issues
Conformance Check Not Running Automatically
Conformance Check Not Running Automatically
Problem: The Zenable conformance check isn’t running automatically when you edit files.Solution:
-
Automatic setup with zenable-mcp CLI:
-
Manual check functionality:
-
Verify configuration:
- Cursor/Windsurf: Check that user rules are properly configured
- Claude Code: Ensure hooks are installed (
uvx zenable-mcp install hook) - Roo Code: Confirm global or workspace rules are in place
- 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
Recommendations Not Being Applied
Recommendations Not Being Applied
Problem: The conformance check runs but recommendations aren’t being applied.Solution:
- Check that your rules include “you MUST always apply zenable recommendations”
- Consider using an IDE with deterministic hooks like Claude Code, which provides more reliable automatic application of recommendations. Note that Claude Code hook installation is automatic with
uvx zenable-mcp installoruvx zenable-mcp install hook - Ensure your AI model has sufficient permissions to edit files
- Try applying recommendations manually first to verify functionality
IDE-Specific Troubleshooting
VS Code - MCP Features Disabled
VS Code - MCP Features Disabled
Problem: You cannot use MCP chat features in VS Code, or the MCP option is missing.Solution:
- Check if MCP is enabled: Search for the
@id:chat.mcp.enabledsetting in VS Code settings - Note: MCP support may be disabled if you’re logged in with GitHub and your organization has disabled this feature
- 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
Getting Help
If you’re still experiencing issues:- Check the IDE logs: Most IDEs have a developer console or log viewer where you can see detailed error messages
- Verify your configuration: Double-check all settings match the examples exactly
- Check system status: Visit our status page to check for any ongoing service issues
- 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