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

# Mcp troubleshooting

> Fix common MCP server issues — startup failures, missing tools, authentication errors, and empty responses.

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

<Tip>New to MCP? Start with the [Get Started](/mcp/install) guide.</Tip>

## 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](/mcp/install) 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](/mcp/install), fully restart the app, and run `npx -y @opencx/mcp` in a terminal to verify the package runs. Use [Cursor](/mcp/clients/cursor) (Agent mode), [Claude Desktop](/mcp/clients/claude-desktop) (full quit), [Claude Code](/mcp/clients/claude-code) (shell `OPENCX_API_KEY`), [VS Code](/mcp/clients/vscode), [Windsurf](/mcp/clients/windsurf), or [Zed](/mcp/clients/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](https://platform.open.cx/settings/access) 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](https://platform.open.cx/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](/mcp/install#remote-server-no-install) 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 **[support@open.cx](mailto:support@open.cx)** with your error message and client name.                                                                                                                                                                                                                                                                                                                                             |

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

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Get Started" icon="download" href="/mcp/install">
    Re-check config JSON and setup steps
  </Card>

  <Card title="Cursor" icon="text-slash" href="/mcp/clients/cursor">
    Agent mode and MCP panel
  </Card>

  <Card title="VS Code" icon="code" href="/mcp/clients/vscode">
    mcp.json and Copilot Chat
  </Card>

  <Card title="Windsurf" icon="water" href="/mcp/clients/windsurf">
    mcp\_config.json and Cascade
  </Card>
</CardGroup>