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

# Troubleshooting

> Common issues and solutions for the Coval MCP server

## Server Not Connecting

If your MCP client reports that it cannot connect to the Coval MCP server:

<AccordionGroup>
  <Accordion title="Try the hosted server instead of local NPX">
    The most common fix. The hosted server at `mcp.coval.dev` avoids local Node.js version issues and package installation problems entirely.

    Replace your config with the [hosted server setup](/mcp/installation#hosted-server-recommended) and restart your client.
  </Accordion>

  <Accordion title="Check that Node.js 20+ is installed">
    Both the hosted (`mcp-remote`) and local (`@covalai/mcp-server`) methods require Node.js to run `npx`.

    ```bash theme={null}
    node --version
    ```

    If you see a version below 20 or `command not found`, install Node.js from [nodejs.org](https://nodejs.org).

    **Windows users:** Make sure Node.js is on your system PATH. After installing, open a new terminal and verify `npx --version` works.
  </Accordion>

  <Accordion title="Verify your config file path">
    The config file must be in the exact location your client expects:

    | Client         | macOS                                                             | Windows                                              |
    | -------------- | ----------------------------------------------------------------- | ---------------------------------------------------- |
    | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | `%APPDATA%\Claude\claude_desktop_config.json`        |
    | Cursor         | `.cursor/mcp.json` (project root)                                 | `.cursor\mcp.json` (project root)                    |
    | Claude Code    | `~/.claude/settings.json` or `.mcp.json`                          | `%USERPROFILE%\.claude\settings.json` or `.mcp.json` |

    **Tip:** On macOS, the `Library` folder is hidden by default. In Finder, press `Cmd+Shift+G` and paste the path, or use the terminal:

    ```bash theme={null}
    open ~/Library/Application\ Support/Claude/
    ```
  </Accordion>

  <Accordion title="Validate your JSON syntax">
    A single syntax error (trailing comma, missing quote, extra bracket) will silently break the entire config.

    Paste your config file contents into [jsonlint.com](https://jsonlint.com) to check for errors.

    Common mistakes:

    * Trailing comma after the last item in an object or array
    * Missing comma between `mcpServers` entries if you have multiple servers
    * Curly quotes (`"` `"`) instead of straight quotes (`"`) — this happens when copying from some websites or chat apps
  </Accordion>

  <Accordion title="Restart your client completely">
    Closing the window is not enough — the MCP server config is only loaded on startup.

    * **Claude Desktop (macOS):** Right-click the dock icon → Quit, or use `Cmd+Q`
    * **Claude Desktop (Windows):** Right-click the system tray icon → Exit
    * **Cursor:** Close all windows and restart the application
  </Accordion>
</AccordionGroup>

## Authentication Errors

<AccordionGroup>
  <Accordion title="Verify your API key">
    1. Go to [Coval Dashboard → Settings → API Keys](https://app.coval.dev/settings)
    2. Confirm the key is active (not revoked or expired)
    3. Copy the key fresh — don't retype it manually
  </Accordion>

  <Accordion title="Check for whitespace or formatting issues">
    Make sure your API key in the config has:

    * No leading or trailing spaces
    * No newlines or line breaks
    * No curly/smart quotes around it

    The `COVAL_API_KEY` value should be the raw key string with no extra characters.
  </Accordion>

  <Accordion title="Hosted server: check the header format">
    If using the hosted server method, verify the header argument is exactly:

    ```
    "X-API-Key: ${COVAL_API_KEY}"
    ```

    The `${COVAL_API_KEY}` variable is resolved from the `env` block at runtime. Make sure:

    * The key name in `env` matches exactly: `COVAL_API_KEY`
    * The header string includes the space after the colon
  </Accordion>
</AccordionGroup>

## Tools Not Appearing

<AccordionGroup>
  <Accordion title="Check MCP logs">
    **Claude Desktop (macOS):**

    ```bash theme={null}
    # List MCP log files
    ls ~/Library/Logs/Claude/mcp*.log

    # View the most recent log
    cat ~/Library/Logs/Claude/mcp-server-coval.log
    ```

    **Claude Desktop (Windows):**

    ```
    %APPDATA%\Claude\logs\mcp*.log
    ```

    Look for connection errors, authentication failures, or stack traces.
  </Accordion>

  <Accordion title="Test the server manually">
    Run the local server directly to see if it starts without errors:

    ```bash theme={null}
    COVAL_API_KEY=your_key_here npx -y @covalai/mcp-server
    ```

    If this shows errors, the issue is with the server or your API key — not your client config.
  </Accordion>

  <Accordion title="Verify API key has correct permissions">
    Without a valid API key, the server may start but expose limited or no tools. Ensure your key is active at [app.coval.dev/settings](https://app.coval.dev/settings).
  </Accordion>
</AccordionGroup>

## Permission Denied Errors

<AccordionGroup>
  <Accordion title="macOS: permission denied on config file">
    If you see `zsh: permission denied` when trying to edit the config file:

    ```bash theme={null}
    # Check current permissions
    ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json

    # Fix permissions (make it readable/writable by you)
    chmod 644 ~/Library/Application\ Support/Claude/claude_desktop_config.json
    ```

    If the file doesn't exist yet, create it:

    ```bash theme={null}
    # Create the directory if needed
    mkdir -p ~/Library/Application\ Support/Claude

    # Create the config file
    touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
    ```

    Then open it in your editor and paste the config from the [Installation guide](/mcp/installation).
  </Accordion>

  <Accordion title="Windows: access denied on config file">
    Try running your text editor as Administrator, or check that the file isn't marked as read-only:

    1. Navigate to `%APPDATA%\Claude\`
    2. Right-click `claude_desktop_config.json` → Properties
    3. Uncheck "Read-only" if checked
  </Accordion>

  <Accordion title="npx permission errors">
    If `npx` fails with permission errors:

    ```bash theme={null}
    # Clear the npx cache
    npx clear-npx-cache

    # Or try running with explicit cache directory
    npm config set cache /tmp/npm-cache --global
    ```

    On macOS/Linux, avoid using `sudo` with npx — instead fix the npm directory permissions:

    ```bash theme={null}
    mkdir -p ~/.npm-global
    npm config set prefix '~/.npm-global'
    export PATH=~/.npm-global/bin:$PATH
    ```
  </Accordion>
</AccordionGroup>

## Firewall or Proxy Issues

If you're on a corporate network or behind a proxy:

* The **hosted server** method needs outbound HTTPS access to `mcp.coval.dev`
* The **local NPX** method needs outbound HTTPS access to `registry.npmjs.org` (to download packages) and `api.coval.dev` (for API calls)

Check with your IT team if these domains are allowed through your firewall or proxy.

If you use an HTTP proxy:

```bash theme={null}
# Set proxy for npm/npx
npm config set proxy http://your-proxy:port
npm config set https-proxy http://your-proxy:port
```

## Still Stuck?

If none of the above resolves your issue:

1. Gather your MCP logs (see [Check MCP logs](#check-mcp-logs) above)
2. Note which client and OS you're using
3. Reach out to [support@coval.dev](mailto:support@coval.dev) or open an issue on [GitHub](https://github.com/coval-ai/mcp-server/issues)