Troubleshooting - Calibrate

Most problems come down to the config file, the API key, or a client that needs a full restart. Work through the section that matches your symptom.

Server not connecting

Try the hosted server first

The hosted server needs no local install and sidesteps Node.js version issues. If the local npx server won’t start, switch to the hosted config while you debug.

Check your Node.js version (local server)

The local server needs Node.js 20+. Check with:

node --version

If it’s older, install Node 20+ from nodejs.org or use the hosted server instead.

Confirm the config file location

The file must be in the exact place your client reads. For Claude Desktop see Config file locations; Cursor uses .cursor/mcp.json and Claude Code manages config via claude mcp.

Validate the JSON

A stray trailing comma or a curly “smart quote” breaks the whole config. Paste it into a JSON validator and confirm every quote is a straight ".

Fully restart the client

Closing the window is not enough — quit the app completely (Claude Desktop: Cmd/Ctrl+Q) and reopen it so it reloads the MCP config.

Authentication errors

Check the key is active

Confirm the key exists and is enabled under Workspace settings → API keys. Copy it fresh rather than retyping it.

Watch for stray whitespace or smart quotes

A leading/trailing space, a newline, or a curly quote around the key will fail auth. Paste it as plain text with no surrounding characters.

Check the header format (hosted server)

For the hosted server the header must be exactly X-API-Key: your_api_key (or X-API-Key: ${CALIBRATE_API_KEY} with the env var set). For the local server the key goes in CALIBRATE_API_KEY_AUTH or the --api-key-auth flag.

Tools not appearing

Check the MCP logs

Your client logs MCP connection and auth errors — Claude Desktop writes them under ~/Library/Logs/Claude/ (macOS). Look for a failed connection or a 401.

Run the server by hand

Test the local server directly and watch the output:

CALIBRATE_API_KEY_AUTH=your_api_key npx -y @dalmia/calibrate-mcp start

Or list the tools over the hosted endpoint:

curl -s -X POST https://mcp.calibrate.artpark.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Confirm the key's permissions

A tool that reads works but a write fails? Check the key is allowed to perform that action in your workspace.

Permission denied errors

macOS / Linux

Fix config-file permissions and create the directory if it’s missing:

chmod 644 "~/Library/Application Support/Claude/claude_desktop_config.json"

Windows

Run your editor as Administrator and make sure the config file isn’t marked Read-only in its file properties.

npx cache errors

Clear the npx cache if a stale download blocks startup:

npx clear-npx-cache

Firewall or proxy issues

The server needs outbound HTTPS to the Calibrate API and, for the hosted setup, to the MCP endpoint on *.run.app. Behind a proxy, set HTTPS_PROXY before launching:

export HTTPS_PROXY=http://your-proxy:8080

Still stuck?

Gather your client’s MCP logs and the exact config you used (with the key redacted), then open an issue on github.com/dalmia/calibrate-mcp.

​Server not connecting

​Authentication errors

​Tools not appearing

​Permission denied errors

​Firewall or proxy issues

​Still stuck?