Common Troubleshooting 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 in your MCP config. See Install for the exact JSON. |
| Tools not visible in Claude Desktop / Cursor | Malformed config JSON or client not restarted | Re-paste the config from Install, save, and fully restart your AI tool. |
| Every tool call returns a 401 error | API key is invalid, revoked, or belongs to a different org | Generate a new key under Settings > API Keys in your OpenCX dashboard and update the config. |
| Tool call succeeds but returns empty data | The org has no data matching your query (e.g. no contacts, no sessions) | Verify with a known-good ID in the dashboard first, then retry the tool call. |
| 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.
Related Documentation
Install
Re-check config JSON and setup steps.
Authentication
API key creation and environment variables.
Use Cases
Common workflows and example prompts.
Tools & Capabilities
Full list of available MCP tools.