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

# Cursor

> Set up and use the OpenCX MCP server in Cursor — project vs global config, agent mode, and debugging.

Cursor supports <Tooltip tip="An open standard that lets AI assistants interact with external tools and data sources.">MCP</Tooltip> servers natively. You can configure OpenCX at the project level (shared with your team) or globally (for your machine only).

<Warning>
  MCP tools only work in **Agent mode**. If you're in Ask mode, Cursor won't
  call any tools. Switch to Agent mode before testing.
</Warning>

## Setup

<Steps>
  <Step title="Open MCP settings">
    Go to **Cursor Settings > MCP** and click **Add new global MCP server** (or **Add new project MCP server** for project-scoped config).
  </Step>

  <Step title="Paste the config">
    ```json theme={"dark"}
    {
      "mcpServers": {
        "opencx": {
          "command": "npx",
          "args": ["-y", "@opencx/mcp"],
          "env": {
            "OPENCX_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```

    Replace `your-api-key-here` with your [OpenCX API key](https://platform.open.cx/settings/access).

    <Tip>
      Prefer zero install? Use the [hosted endpoint](/mcp/install#remote-server-no-install) instead — same tools, no Node.js required:

      ```json theme={"dark"}
      {
        "mcpServers": {
          "opencx": {
            "url": "https://api.open.cx/mcp",
            "headers": {
              "Authorization": "Bearer your-api-key-here"
            }
          }
        }
      }
      ```
    </Tip>
  </Step>

  <Step title="Verify">
    Open a new Agent mode chat and ask: *"List my recent chat sessions."*

    If you get results, the server is connected.
  </Step>
</Steps>

## Project vs Global Config

| Scope       | File                            | Shared with team      | Use when                           |
| ----------- | ------------------------------- | --------------------- | ---------------------------------- |
| **Project** | `.cursor/mcp.json` in repo root | Yes (commit the file) | Team shares the same MCP setup     |
| **Global**  | `~/.cursor/mcp.json`            | No                    | Personal tools across all projects |

<Note>
  When using project-scoped config, reference `OPENCX_API_KEY` as an environment
  variable in the `env` block — don't hardcode the key in a committed file. Each
  team member sets the key in their local shell profile or `.env`.
</Note>

## Agent Mode vs Ask Mode

Cursor has two chat modes:

* **Agent mode** — can call MCP tools, read/write files, run commands. This is where OpenCX tools work.
* **Ask mode** — read-only, no tool calls. MCP tools are unavailable.

If your prompts aren't triggering OpenCX tools, check the mode toggle at the top of the chat panel.

## Debugging

If the server isn't connecting or tools aren't appearing:

1. **Check the MCP panel** — go to **Cursor Settings > MCP**. Each server shows a status indicator (green = connected, red = error). Click the server name to see logs.
2. **Restart the server** — click the refresh icon next to the server name in the MCP panel.
3. **Check the output** — Cursor shows MCP tool calls and responses inline in the chat. If a tool call fails, the error message appears in the response.
4. **Verify Node.js** — run `node --version` in Cursor's terminal. The MCP server requires Node.js 18+.

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Get Started" icon="download" href="/mcp/install">
    API key setup and all client configs
  </Card>

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

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

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>