# Connecting Cursor

This guide walks through connecting [Cursor](https://cursor.com) to your OneHazel workflows over MCP. Cursor's Agent / Composer can then call any workflow you've exposed.

If you haven't already, see [Connecting Claude Desktop](/mcp/connecting-claude-desktop) first — Steps 1–3 (expose workflows, create an MCP-enabled API key, find your MCP URL) are identical and won't be repeated here.

## Step 4 — Add OneHazel to Cursor's MCP settings

Cursor reads MCP servers from `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` at the project root (per-project).

### Via the Cursor UI

1. Open Cursor → **Settings** → **Features** → **Model Context Protocol**
2. Click **+ Add new MCP server**
3. Fill in:
   - **Name:** `onehazel`
   - **Type:** `http`
   - **URL:** `https://api.onehazel.com/mcp-server`
4. Add a header:
   - **Key:** `Authorization`
   - **Value:** `Bearer oh_live_YOUR_KEY_HERE`
5. Save

### Via `mcp.json` directly

Edit `~/.cursor/mcp.json` (create if missing):

```json
{
  "mcpServers": {
    "onehazel": {
      "type": "http",
      "url": "https://api.onehazel.com/mcp-server",
      "headers": {
        "Authorization": "Bearer oh_live_YOUR_KEY_HERE"
      }
    }
  }
}
```

Substitute `oh_live_YOUR_KEY_HERE` with your plaintext API key.

::: tip Backward compatibility
The legacy per-operator URL `https://api.onehazel.com/mcp-server/<your_operator_id>` still works. If your config already uses it, no change is required.
:::

::: tip Per-project keys
For team setups, prefer per-project `.cursor/mcp.json` so each project gets its own least-privileged key. Don't commit the file with the bearer in plaintext — gitignore it and document the setup in your README instead.
:::

## Step 5 — Reload Cursor's MCP servers

In **Settings → MCP**, click the refresh icon next to `onehazel`. Cursor opens a connection and calls `initialize`. A green dot next to the entry means the handshake succeeded.

## Step 6 — Verify

Open Cursor's Agent or Composer pane and ask:

> "List the OneHazel tools you have access to."

The assistant calls `tools/list` and reports back. Each entry is one of your `mcp_exposed` workflows.

To exercise a tool:

> "Run my `refund_lookup` workflow for customer `cust_123` and tell me what came back."

Cursor's agent calls `tools/call`, OneHazel runs the workflow against your real connections, and the result lands in the chat.

## Troubleshooting

Same error-code table as Claude Desktop — see [Troubleshooting in the Claude Desktop guide](/mcp/connecting-claude-desktop#troubleshooting) and the [error codes table](/mcp/api-reference#error-codes).

Cursor-specific gotchas:

| Symptom | Likely cause | Fix |
|---|---|---|
| Server stuck on "Connecting…" | Cursor caches old config | Quit + reopen Cursor; settings reload isn't always enough |
| Tools show up but Agent never uses them | Agent doesn't see a fit | Mention the tool name explicitly in your prompt, or reword the trigger schema's field descriptions to be more declarative |
| 401 immediately after editing the key | Stale connection on the old token | Hit refresh in **Settings → MCP** to reconnect |

## What's next

- [API Reference](/mcp/api-reference) — what each JSON-RPC method does, request / response shapes
- [Security](/mcp/security) — auth model, allowlists, rate limits, audit