Mcp get started

Add the OpenCX server to your AI client so it can manage contacts, sessions, training, and more through natural language.

Fastest path: add https://api.open.cx/mcp to your client and sign in — no API key to create or rotate. See Connect with your OpenCX sign-in below.

Prerequisites: for the sign-in setup, an OpenCX account. For the API-key setups below, an OpenCX API key (created below) and Node.js 18+ for the local npx option.

Create an API key

Open your OpenCX dashboard 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.

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.

{
  "mcpServers": {
    "opencx": {
      "command": "npx",
      "args": ["-y", "@opencx/mcp"],
      "env": {
        "OPENCX_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "opencx": {
      "command": "npx",
      "args": ["-y", "@opencx/mcp"],
      "env": {
        "OPENCX_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "servers": {
    "opencx": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@opencx/mcp"],
      "env": {
        "OPENCX_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "opencx": {
      "command": "npx",
      "args": ["-y", "@opencx/mcp"],
      "env": {
        "OPENCX_API_KEY": "your-api-key-here"
      }
    }
  }
}

export OPENCX_API_KEY="your-api-key-here"
claude mcp add opencx -- npx -y @opencx/mcp

Each client has its own config file and UI. See Cursor, Claude Desktop, Claude Code, VS Code, Windsurf, and Zed.

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.

The hosted endpoint also accepts your own OpenCX sign-in, so a teammate can connect a client without anyone creating or sharing an API key. It is the same URL as the API-key setup — what differs is that you leave the Authorization header off.

Add the server to your client

Add https://api.open.cx/mcp as a remote (Streamable HTTP) server with no Authorization header — that header is what suppresses the sign-in. The client registers itself and opens a browser window.

claude mcp add --transport http opencx https://api.open.cx/mcp

{
  "mcpServers": {
    "opencx": {
      "type": "http",
      "url": "https://api.open.cx/mcp"
    }
  }
}

{
  "servers": {
    "opencx": {
      "type": "http",
      "url": "https://api.open.cx/mcp"
    }
  }
}

Sign in to OpenCX if you are not already, choose which organization the app may work in, and select Connect. The client is connected from that point on and refreshes access by itself.To skip the choice, copy the server URL from Settings > API Keys > Connected apps instead. It ends in ?org=<your organization id>, so that organization is already selected when you sign in. You can still switch to another one before connecting, and some clients may ask you to choose anyway.Connecting to a second organization is the same URL again under a different server name — each connection is approved separately.

What the client can do: exactly what your own role lets you do, nothing more. Permissions are re-checked on every request, so narrowing someone’s role — or removing them from the organization — takes effect immediately, with no reconnection and no key to revoke. Disconnecting: open Settings > API Keys > Connected apps in the organization and choose Disconnect. Access stops at once. Each teammate sees and manages only their own connections.

Clients that cannot open a browser (headless CI, servers, scripts) should keep using an API key — see Remote server below.

Remote server (no install)

OpenCX also hosts the MCP server over at https://api.open.cx/mcp. Nothing to install or keep updated — authenticate with the same API key as a bearer token:

claude mcp add --transport http opencx https://api.open.cx/mcp \
  --header "Authorization: Bearer your-api-key-here"

{
  "mcpServers": {
    "opencx": {
      "type": "http",
      "url": "https://api.open.cx/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

{
  "servers": {
    "opencx": {
      "type": "http",
      "url": "https://api.open.cx/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

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 hosted endpoint accepts either:

your OpenCX sign-in, for a client you use yourself — you pick the organization when you approve it, the connection carries your permissions, and it is managed from Settings > API Keys > Connected apps;
an organization API key, for servers, CI and scripts — the key carries the scopes you gave it, independently of any person.

Both reach the same tools. Organization API keys are unaffected by the sign-in option and keep working exactly as before. The local npx 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.

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

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.

Prompt Library

Ready-to-use prompts by domain

Cursor

Project config, agent mode, debugging

VS Code

mcp.json and Copilot

Troubleshooting

Debug connection and authentication issues

Overview

Client Guides

Reference

Remote server (no install)

Authentication

Self-hosted instances

Prompt Library

Cursor

VS Code

Troubleshooting

​Connect with your OpenCX sign-in

​Remote server (no install)

​Authentication

​Self-hosted instances

​Related Documentation

Prompt Library

Cursor

VS Code

Troubleshooting

Connect with your OpenCX sign-in

Remote server (no install)

Authentication

Self-hosted instances

Related Documentation