# Cursor Setup

Official source: https://cursor.com/docs/mcp.md

Cursor supports remote MCP servers through Cursor settings and `mcp.json`. Core should usually be configured globally so it follows you across projects.

Core MCP server URL:

```text
https://core.gradien.ai/mcp
```

Global config path:

```text
~/.cursor/mcp.json
```

Project config path:

```text
.cursor/mcp.json
```

## Recommended Setup

Run the guided installer:

```bash
npx -y @gradien/core-agent-setup
```

The installer creates a Core signup/login session, backs up existing Cursor MCP config, and adds Core where Cursor can load it.

## Manual Config

The expected global config shape is:

```json
{
  "mcpServers": {
    "core": {
      "url": "https://core.gradien.ai/mcp"
    }
  }
}
```

If the file already contains other MCP servers, preserve them and add only the `core` entry.

Do not put bearer tokens or connector keys in Cursor config unless OAuth is impossible and you intentionally choose that fallback.

## Load and Authenticate

Cursor may not hot-load new MCP servers in an existing chat.

1. Reload Cursor with `Cmd+Shift+P` -> `Developer: Reload Window`, or fully quit and relaunch Cursor.
2. Open Cursor Settings.
3. Go to Features -> Model Context Protocol.
4. Find Core. It may appear as `core` or `user-core`.
5. Click Connect or Authenticate.
6. Approve Core in the browser.

If only an `mcp_auth` tool is visible, Core is present but not authenticated yet. Complete the OAuth step from Cursor settings or by using the visible auth tool.

## If Cursor Hangs During OAuth

If Cursor stays on `Waiting for callback...` or `Exchanging token...` after the browser returned to Cursor:

1. Stop clicking Connect/Allow repeatedly.
2. Fully quit and relaunch Cursor.
3. Try Connect once more.
4. Check Cursor MCP Logs in the Output panel: `Cmd+Shift+U` -> `MCP Logs`.

Repeated unauthenticated requests to `/mcp` mean Cursor can reach Core but did not complete or store OAuth. That is usually an OAuth callback state issue, not a bad URL.

## Fallback

If OAuth keeps hanging after one clean relaunch, a scoped Core connector key can be used as a fallback. Store it as locally and narrowly as possible, prefer environment-variable interpolation if Cursor supports it, and rotate the key later.