> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenable.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<iframe width="560" height="315" src="https://www.youtube.com/embed/fyxtiF_e2bo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

## Troubleshooting Tools

<AccordionGroup>
  <Accordion title="Using the Zenable CLI for Diagnostics">
    **Problem**: You need to diagnose installation issues or verify your setup.

    **Solution**:
    Use the Zenable CLI diagnostic commands:

    ```bash theme={null}
    # View logs to diagnose issues
    zenable logs --tail 50

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

    # Check version and environment
    zenable version

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

    # Enable debug mode for detailed output
    zenable --debug install
    ```

    <Tip>
      **Seeing an "outdated" message?** If you're getting a message that zenable is outdated, upgrade it with:

      ```bash theme={null}
      zenable
      ```
    </Tip>

    For deeper MCP server debugging, use the MCP Inspector:

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="Quick Setup and Repair">
    **Problem**: Your MCP configuration or hooks aren't working correctly.

    **Solution**:
    The Zenable CLI can automatically install and repair configurations:

    ```bash theme={null}
    # Fresh installation (detects IDEs automatically)
    zenable install

    # Overwrite existing configuration (use with caution)
    zenable install --overwrite
    ```

    <Warning>
      **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.
    </Warning>

    For specific IDE repairs:

    ```bash theme={null}
    # Repair specific IDE configuration
    zenable install cursor --overwrite
    zenable install windsurf --overwrite
    zenable install codex --overwrite
    zenable install claude --overwrite
    ```
  </Accordion>
</AccordionGroup>

## Common Issues

### Installation Issues

<AccordionGroup>
  <Accordion title="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](/integrations/mcp/getting-started) to install Node.js and npm for your platform.

    After installation:

    1. Verify installation: `npx --version`
    2. Restart your terminal/IDE
  </Accordion>

  <Accordion title="MCP Server Not Showing Up in IDE">
    **Problem**: After adding the configuration, the Zenable MCP server doesn't appear in your IDE.

    **Solution**:

    1. **Automatic fix with Zenable CLI**:
       ```bash theme={null}
       # Reinstall MCP configuration for all detected IDEs
       zenable install

       # For a specific IDE with overwrite
       zenable install cursor --overwrite
       ```

    2. **Debug the issue**:
       ```bash theme={null}
       # Check logs for errors
       zenable logs --tail 100

       # Verify installation with debug output
       zenable --debug install --dry-run
       ```

    3. Validate your JSON syntax - ensure proper brackets and commas

    4. Restart your IDE completely (not just reload)
  </Accordion>
</AccordionGroup>

### Connection Issues

<AccordionGroup>
  <Accordion title="Connection Timeout">
    **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
  </Accordion>

  <Accordion title="SSL/TLS Certificate Errors">
    **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
  </Accordion>
</AccordionGroup>

### Usage Issues

<AccordionGroup>
  <Accordion title="Conformance Check Not Running Automatically">
    **Problem**: The Zenable conformance check isn't running automatically when you edit files.

    **Solution**:

    1. **Automatic setup with Zenable CLI**:
       ```bash theme={null}
       # Install hooks for Claude Code and Cursor
       zenable install hook

       # Full installation (MCP + hooks)
       zenable install
       ```

    2. **Manual check functionality**:
       ```bash theme={null}
       # Test conformance checking manually
       zenable check '**/*.py'

       # Check uncommitted changes
       zenable check --uncommitted
       ```

    3. **Verify configuration**:
       * **[Claude Code](/integrations/mcp/ide/claude-code)**: Ensure hooks are installed (`zenable install hook claude`)
       * **[Cursor](/integrations/mcp/ide/cursor)**: Ensure hooks are installed (`zenable install hook cursor`)
       * **[Windsurf](/integrations/mcp/ide/windsurf)/[Codex](/integrations/mcp/ide/codex)/[Antigravity](/integrations/mcp/ide/antigravity)**: Check that user rules are properly configured
       * **[Roo Code](/integrations/mcp/ide/roo)**: 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
  </Accordion>

  <Accordion title="Recommendations Not Being Applied">
    **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](/integrations/mcp/ide/claude-code) or [Cursor](/integrations/mcp/ide/cursor), which provide more reliable automatic application of recommendations. Note that hook installation is automatic with `zenable install` or `zenable install hook`
    3. Ensure your AI model has sufficient permissions to edit files
    4. Try applying recommendations manually first to verify functionality
  </Accordion>
</AccordionGroup>

## IDE-Specific Troubleshooting

<AccordionGroup>
  <Accordion title="VS Code - MCP Features Disabled">
    **Problem**: You cannot use MCP chat features in [VS Code](/integrations/mcp/ide/vscode), 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](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_enable-mcp-support-in-vs-code).
  </Accordion>
</AccordionGroup>

## 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](https://zenable.io/status?utm_source=docs\&utm_medium=mcp-troubleshooting\&utm_content=status) to check for any ongoing service issues
4. **Contact support**: Post on our [feedback page](https://zenable.io/feedback?utm_source=docs\&utm_medium=mcp-troubleshooting\&utm_content=feedback) 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](https://zenable.io/feedback?utm_source=docs\&utm_medium=mcp-troubleshooting\&utm_content=support) to find and vote for features or bug fixes you'd like to see, or contact our support team.