Mcp troubleshooting - Open.cx Docs

Before debugging, confirm your API key is valid and Node.js 18+ is in your PATH.

New to MCP? Start with the Get Started guide.

Common Scenarios

Symptom	Likely cause	Fix
Server crashes on startup with “OPENCX_API_KEY is required”	API key not set in your client config	Add `OPENCX_API_KEY` to the `env` block (or your client’s equivalent). See Get Started for the exact JSON.
Tools not listed, never run, or Claude Code reports “MCP server not found”	Malformed JSON, editor not restarted, wrong mode, missing env on PATH, or stale `npx` cache	Re-paste config from Get Started, fully restart the app, and run `npx -y @opencx/mcp` in a terminal to verify the package runs. Use Cursor (Agent mode), Claude Desktop (full quit), Claude Code (shell `OPENCX_API_KEY`), VS Code, Windsurf, or Zed for client-specific steps.
Every tool call returns 401 or 403	Invalid or revoked key, wrong org, or insufficient access for the operation	Create a new key under Settings > API Keys in your OpenCX dashboard and update the config.
Tool call succeeds but the payload is empty	No matching data in the org (e.g. no sessions yet)	Confirm in the inbox or contacts, then retry with a known-good id.
Remote endpoint (`api.open.cx/mcp`) returns 401 on connect	Missing or malformed `Authorization` header	Send `Authorization: Bearer <api-key>` on the connection — see Remote server for per-client config.
Remote endpoint returns 405 on GET	Expected — the hosted endpoint is stateless and offers no server-push SSE stream	Nothing to fix; MCP clients fall back to regular request/response automatically.
None of the above	—	Contact support at [email protected] with your error message and client name.

Every tool call is logged in your OpenCX dashboard — check Settings > Audit Logs to see whether the call reached the API.

Get Started

Re-check config JSON and setup steps

Cursor

Agent mode and MCP panel

VS Code

mcp.json and Copilot Chat

Windsurf

mcp_config.json and Cascade