Skip to main content

​
Server Not Connecting

If your MCP client reports that it cannot connect to the Coval MCP server:
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 and restart your client.
Both the hosted (mcp-remote) and local (@covalai/mcp-server) methods require Node.js to run npx.
node --version
If you see a version below 20 or command not found, install Node.js from nodejs.org.Windows users: Make sure Node.js is on your system PATH. After installing, open a new terminal and verify npx --version works.
The config file must be in the exact location your client expects:
ClientmacOSWindows
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:
open ~/Library/Application\ Support/Claude/
A single syntax error (trailing comma, missing quote, extra bracket) will silently break the entire config.Paste your config file contents into 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
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

​
Authentication Errors

  1. Go to Coval Dashboard → Settings → API Keys
  2. Confirm the key is active (not revoked or expired)
  3. Copy the key fresh — don’t retype it manually
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.
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

​
Tools Not Appearing

Claude Desktop (macOS):
# 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.
Run the local server directly to see if it starts without errors:
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.
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.

​
Permission Denied Errors

If you see zsh: permission denied when trying to edit the config file:
# 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:
# 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.
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
If npx fails with permission errors:
# 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:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

​
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: 
# 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 above)
  2. Note which client and OS you’re using
  3. Reach out to support@coval.dev or open an issue on GitHub