> ## 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 get started

> Add the OpenCX MCP server to Claude Desktop, Cursor, VS Code, Windsurf, or Claude Code — from API key to first query in minutes.

Add the OpenCX <Tooltip tip="Model Context Protocol — an open standard that lets AI assistants call tools on your behalf.">MCP</Tooltip> server to your AI client so it can manage contacts, sessions, training, and more through natural language.

<Tip>
  Prefer zero install? Connect to the hosted endpoint at
  `https://api.open.cx/mcp` — see [Remote server](#remote-server-no-install)
  below. The local `npx` setup only requires Node.js 18+.
</Tip>

**Prerequisites:** an OpenCX API key (created below). Node.js 18+ for the local `npx` setup.

<Steps>
  <Step title="Create an API key">
    Open your [OpenCX dashboard](https://platform.open.cx/settings/access) and navigate to **Settings > API Keys > Create API Key**. Give it a descriptive name (e.g. "Cursor MCP") and copy the key immediately — it is only shown once.
  </Step>

  <Step title="Add to your AI client">
    Paste the configuration below into your client's MCP settings. Replace `your-api-key-here` with the key you just copied.

    <CodeGroup>
      ```json Claude Desktop theme={"dark"}
      {
        "mcpServers": {
          "opencx": {
            "command": "npx",
            "args": ["-y", "@opencx/mcp"],
            "env": {
              "OPENCX_API_KEY": "your-api-key-here"
            }
          }
        }
      }
      ```

      ```json Cursor theme={"dark"}
      {
        "mcpServers": {
          "opencx": {
            "command": "npx",
            "args": ["-y", "@opencx/mcp"],
            "env": {
              "OPENCX_API_KEY": "your-api-key-here"
            }
          }
        }
      }
      ```

      ```json VS Code theme={"dark"}
      {
        "servers": {
          "opencx": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@opencx/mcp"],
            "env": {
              "OPENCX_API_KEY": "your-api-key-here"
            }
          }
        }
      }
      ```

      ```json Windsurf theme={"dark"}
      {
        "mcpServers": {
          "opencx": {
            "command": "npx",
            "args": ["-y", "@opencx/mcp"],
            "env": {
              "OPENCX_API_KEY": "your-api-key-here"
            }
          }
        }
      }
      ```

      ```bash Claude Code theme={"dark"}
      export OPENCX_API_KEY="your-api-key-here"
      claude mcp add opencx -- npx -y @opencx/mcp
      ```
    </CodeGroup>

    <Note>
      Each client has its own config file and UI. See [Cursor](/mcp/clients/cursor), [Claude Desktop](/mcp/clients/claude-desktop), [Claude Code](/mcp/clients/claude-code), [VS Code](/mcp/clients/vscode), [Windsurf](/mcp/clients/windsurf), and [Zed](/mcp/clients/zed).
    </Note>
  </Step>

  <Step title="Verify the connection">
    Ask your AI assistant one of these prompts to confirm the server is connected:

    * *"List my recent chat sessions"*
    * *"Show me CSAT scores from the last week"*
    * *"Search my knowledge base for refund policy"*

    If you get results back, the connection is working.
  </Step>
</Steps>

## Remote server (no install)

OpenCX also hosts the MCP server over <Tooltip tip="The MCP Streamable HTTP transport — a single HTTP endpoint that speaks JSON-RPC.">Streamable HTTP</Tooltip> at `https://api.open.cx/mcp`. Nothing to install or keep updated — authenticate with the same API key as a bearer token:

<CodeGroup>
  ```bash Claude Code theme={"dark"}
  claude mcp add --transport http opencx https://api.open.cx/mcp \
    --header "Authorization: Bearer your-api-key-here"
  ```

  ```json Cursor / Claude Desktop theme={"dark"}
  {
    "mcpServers": {
      "opencx": {
        "type": "http",
        "url": "https://api.open.cx/mcp",
        "headers": {
          "Authorization": "Bearer your-api-key-here"
        }
      }
    }
  }
  ```

  ```json VS Code theme={"dark"}
  {
    "servers": {
      "opencx": {
        "type": "http",
        "url": "https://api.open.cx/mcp",
        "headers": {
          "Authorization": "Bearer your-api-key-here"
        }
      }
    }
  }
  ```
</CodeGroup>

The remote and local servers expose the same tools; pick whichever fits your environment. Self-hosted deployments serve the same endpoint at `https://your-instance/mcp`.

## Authentication

The MCP server authenticates with a per-organization API key passed through the `OPENCX_API_KEY` environment variable.

| Variable          | Required | Default               | Description                              |
| ----------------- | -------- | --------------------- | ---------------------------------------- |
| `OPENCX_API_KEY`  | Yes      | —                     | Your OpenCX API key                      |
| `OPENCX_BASE_URL` | No       | `https://api.open.cx` | API base URL for self-hosted deployments |

**Rotating keys:** Create a new key in **Settings > API Keys**, update your MCP client config, then delete the old key from the dashboard.

<Warning>
  Never commit API keys to version control. Use your local MCP client config
  file or CI secrets for automated environments.
</Warning>

## Self-hosted instances

If you run a self-hosted OpenCX deployment, set `OPENCX_BASE_URL` to your instance URL. The server requires HTTPS unless targeting `localhost` for local development.

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Prompt Library" icon="message" href="/mcp/prompts">
    Ready-to-use prompts by domain
  </Card>

  <Card title="Cursor" icon="text-slash" href="/mcp/clients/cursor">
    Project config, agent mode, debugging
  </Card>

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

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Debug connection and authentication issues
  </Card>
</CardGroup>