Free guide · Cursor

Cursor setup that survives updates

Level · Intermediate

A working Cursor install is not the same thing as a setup you can rebuild. This is the orientation page: what the three surfaces are, where your configuration actually lives, and how to arrange things so an update does not quietly undo your afternoon.

The short version

Know which surface you are on — Desktop, CLI, or Cloud Agents. They share an account, not a machine — the three surfaces.
Configuration lives in .cursor/ in your project and ~/.cursor/ in your home directory — where config lives.
Keep the portable parts in a small config repo so a new machine is a clone, not an archaeology project — the config repo pattern.
After an update, verify in this order: rules load, then MCP, then the other surfaces — after an update.

Brand new to Cursor? Ignore the box — the explanation starts below.

New to Cursor? Start here

Cursor is three things, not one

The single most useful idea on this page: “Cursor” is not one program that happens to have several windows. It is three environments that share your account and very little else. Almost every confusing support thread comes from someone assuming a setting they changed in one place applies in all three.

Surface	What it is	Runs on
Desktop	The editor you click. Chat, Inline Edit, rules, MCP — the surface almost every tutorial screenshot assumes.	Your machine
CLI	Agent work from a terminal. Shares your MCP configuration with the editor.	Your machine
Cloud Agents	A remote machine that clones your repo and works on it. Formerly called Background Agents.	Cursor’s infrastructure

If you take one thing away: Desktop and CLI are your computer, with your files and your installed tools. Cloud Agents is somebody else’s computer that has a copy of your repository. “It works locally but not in the cloud agent” is usually not a bug — it is that distinction doing exactly what it says.

Pick one primary surface for your first week. Mixing Desktop experiments with Cloud Agent runs while you are still learning is how people arrive at the conclusion that “MCP is flaky,” when in fact they changed something in one environment and tested it in another.

Grok Bot is a fourth product surface, not a fourth window of the editor: a separate desktop and iPhone app whose Bots work on a persistent cloud computer. It shares your Cursor account and almost none of the files in this table. The orientation page is Grok Bot: info, FAQ, and examples.

The detail

Where configuration actually lives

Two directories matter, and they are both called .cursor — one in your project, one in your home directory. Project first:

your-project/
└── .cursor/
    ├── rules/
    │   └── conventions.mdc     project rules (.mdc only)
    ├── mcp.json                project MCP servers
    ├── environment.json        Cloud Agent environment
    └── cli.json                CLI permissions

And the user-level one:

~/.cursor/
├── rules/                      machine-local user rules
├── mcp.json                    global MCP servers
├── permissions.json            user permissions
└── cli-config.json             CLI global config

On Windows the home-directory one is %USERPROFILE%\.cursor\. Cursor’s CLI documentation gives the global config path as $env:USERPROFILE\.cursor\cli-config.json on Windows and ~/.cursor/cli-config.json on macOS and Linux. You can move the whole directory with CURSOR_CONFIG_DIR, and on Linux and BSD, XDG_CONFIG_HOME is respected — $XDG_CONFIG_HOME/cursor/cli-config.json.

A correction to something this site previously stated, and to a claim you will find repeated widely: an %APPDATA%\Cursor path for general editor settings is not documented by Cursor. Because Cursor is built on VS Code, a user-data directory of that shape does exist in practice — but it is not in the official documentation, so treat it as an observation about the build rather than a supported location, and do not design your backup strategy around it. The .cursor directories above are the documented ones.

The distinction that actually protects you is simpler than any exact path: the application directory is disposable, your .cursor directories are not. Anything sitting where the installer put the program will be replaced by the next update. Never store configuration there.

Rules, briefly

Project rules live in .cursor/rules as .mdc files and are version-controlled with your codebase. User rules are global to your environment and set under Customize → Rules. When several apply, the documented order is Team Rules → Project Rules → User Rules, all merged, with earlier sources winning conflicts.

Two traps worth knowing before you write your first rule: a .md file in .cursor/rules is ignored — the extension must be .mdc — and user rules apply to Agent (Chat) but not to Inline Edit. The full treatment, including the four rule types and how to scope rules to specific folders, is in .cursorrules is deprecated.

MCP, briefly

MCP servers are configured in .cursor/mcp.json for a project and ~/.cursor/mcp.json globally. The two files are merged, and if the same server name appears in both, the project one takes priority. The CLI uses the same configuration as the editor.

When something does not connect, the first move is always the same: open the Output panel with Cmd+Shift+U or Ctrl+Shift+U and select MCP Logs. The full diagnosis path is in MCP server stuck red in Cursor.

The config repo pattern

Here is the setup that survives both updates and new laptops. It is not clever; it is just written down, which is the part most people skip.

Keep a small, dedicated config repo — separate from any product repo — holding the user-level pieces you actually care about: your global mcp.json, any user rules, and a short README saying which surface each applies to. Note that user rules stored as files under ~/.cursor/rules stay on the machine and do not sync, which is exactly why they need to live somewhere you control.
Keep project rules in the project. They belong in .cursor/rules, committed alongside the code they describe. Resist pasting the same two-thousand-word manifesto into every repository you own — scope rules instead.
Write down what you installed by hand. Every CLI tool you installed once and forgot about is a step your Cloud Agent environment does not know to perform. That list belongs in your install script, not in your memory.
Diff after updates. When Cursor ships a change, compare your config repo against what the editor is now reading. New settings keys get added there, not in a screenshot in a group chat.

Verifying after an update

Work in this order. It is deliberately narrow-to-wide, so a failure tells you something specific instead of leaving you re-testing everything:

Reopen Desktop once before debugging anything else, so any first-run migration completes.
Confirm rules load. Open a fresh chat and ask which rules are active and where each came from. Do not verify this by reading your own files — you will see what you meant to write.
Check MCP from that same window, via MCP Logs. One failing server does not take the others down, so a broken one can sit unnoticed for weeks.
Only then test the other surfaces. If the CLI disagrees with Desktop, you have a configuration question. If a Cloud Agent disagrees with both, you almost certainly have an environment question instead — repo vs environment covers that.

What to read next

Running Claude alongside Cursor? Using Claude with Cursor covers which tool owns what — and note that Cursor reads CLAUDE.md too, which surprises most people; that is unpacked in CLAUDE.md vs .cursor/rules.