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 MCP server to your AI client so it can manage contacts, sessions, training, and more through natural language.

Prerequisites: Node.js 18+ and an OpenCX API key (created below).

1. 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.

2. 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.

   Claude Desktop

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

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

3. 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.

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.

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.

---

Related Documentation

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