MCP Server
Troubleshooting
Common issues and solutions for the Zenable MCP Server integration.
Overview
This guide helps you resolve common issues with the Zenable MCP Server integration in your IDE.Video Tutorial
Troubleshooting Tools
Using the MCP Inspector
Using the MCP Inspector
Problem: You need to debug MCP server issues or verify the server is working correctly.Solution:
Run the MCP Inspector tool and follow the steps in the video tutorial: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
Common Issues
API Key Formatting: A common mistake is adding a space after
API_KEY: in your configuration. Make sure there’s no space between the colon and your key:- ✅ Correct:
API_KEY:your-key-here - ❌ Incorrect:
API_KEY: your-key-here
API Key Issues
Invalid API Key Error
Invalid API Key Error
Problem: You’re seeing an “Invalid API Key” error when trying to use the Zenable MCP server.Solution:
Check that the API key is properly formatted in your configuration:
- Make sure to replace
<YOUR_ZENABLE_API_KEY>with your actual key - Ensure there are no extra spaces or quotes around the key
- Important: When adding your API key, make sure there’s no space between
API_KEY:and your key value (e.g.,API_KEY:your-key-herenotAPI_KEY: your-key-here)
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 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:
- Verify the configuration file location:
- Cursor: Check your
mcp.jsonfile location - Windsurf: Ensure
mcp_config.jsonis in the correct directory - Kiro: Confirm
~/.kiro/settings/mcp.jsonexists - Roo Code: Check
mcp_settings.jsonor.roo/mcp.json
- Cursor: Check your
- Validate your JSON syntax - ensure proper brackets and commas
- Restart your IDE completely (not just reload)
- Check IDE logs for any error messages
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:
- Verify you’ve added the required rules/hooks for your IDE:
- Cursor/Windsurf: Check that user rules are properly configured
- Kiro: Ensure agent hooks are set up correctly
- 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 Kiro, which provides more reliable automatic application of recommendations
- Ensure your AI model has sufficient permissions to edit files
- Try applying recommendations manually first to verify functionality
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
- 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