Setting Up Cursor: Rules, MCP Servers and Cloud Agents

Installing an AI code editor takes two minutes. Getting it to actually behave like it knows your codebase takes a little longer — and most of that time goes into three settings most people never open in their first week: rules, MCP servers, and (once you're comfortable) cloud agents. This is a practical setup pass for Cursor, covering what each of those three systems does, the exact file formats and commands involved, and a minimal checklist for getting from a fresh install to a configured workspace in one sitting.

Cursor Freemium

The AI-first code editor with agents, background agents and fast autocomplete

Free plan, paid from $20/mo

🔥 Save 20% with annual billing

9.0 Visit ↗

None of this is exotic — it's the same handful of files a lot of experienced Cursor users already carry from project to project. The goal here is to save you the trial and error of discovering them one at a time.

Start with Rules, Not a Giant System Prompt

The instinct when you first open Cursor is to paste a long "here's how I like my code" message into chat and hope it sticks. It won't — chat context resets, and pasted instructions don't travel with the repo. Cursor's actual mechanism for durable, project-specific instructions is project rules: .mdc files that live in a .cursor/rules directory and are checked into version control alongside your code.

A plain .md file in that directory is silently ignored — the rules system specifically needs the .mdc extension, because the frontmatter at the top of the file is what tells Cursor when and how to use it. A minimal rule looks like this:

---
description: RPC service conventions and patterns for the backend
alwaysApply: false
---

- Define each service in its own file under `src/services/`
- Always validate inputs at the service boundary before passing data
- Return structured error objects with a `code` and `message` field

Because rules are just files in the repo, they show up in code review like anything else — a teammate can propose a change to a rule the same way they'd propose a change to a linter config, which is a much better failure mode than instructions that live only in someone's chat history.

The Four Ways a Rule Can Apply

Three frontmatter fields — description, globs, and alwaysApply — combine to produce four distinct behaviors, and picking the right one matters more than the wording of the rule itself:

A good default split: put your tech stack, folder structure and non-negotiable conventions in one alwaysApply: true rule, put framework- or directory-specific conventions behind globs (like app/routers/**/*.py for API-layer rules), and leave anything narrow or situational as agent-selected or manual so it doesn't compete for space in every single request. Loading every rule into every conversation regardless of relevance is the fastest way to make an agent-selected rule ignored — the agent has to actually read the description to decide it matters, and a wall of always-on text buries that signal.

Wiring In MCP Servers

Rules tell Cursor how to write code; MCP servers give it something new to do — query a database, search the web, open a ticket. Cursor reads MCP configuration from a JSON file called mcp.json, and it looks in two places depending on scope: .cursor/mcp.json in the project root for servers specific to that repo, and ~/.cursor/mcp.json in your home directory for servers you want available everywhere.

The format is the same in both locations — an mcpServers object keyed by server name. A local server launched as a subprocess looks like this:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

A remote server reached over HTTP skips command entirely and points at a URL instead:

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

You can also add servers through Cursor's Settings → Tools & MCP panel, or from the built-in marketplace at cursor.com/marketplace, without hand-editing JSON at all — the file-based approach is mainly worth it when you want a server checked into the repo so the rest of the team gets it for free. Browse the full catalog for Cursor at /apps/cursor/mcp-servers, and keep secrets in the env/headers block rather than hard-coded into args, since that file often ends up committed.

Three MCP Servers Worth Adding First

Rather than installing everything in the marketplace, it's worth starting with servers that touch systems you're already using outside the editor:

Supabase MCP 🔌 MCP serverFreemium

Manage Supabase projects, databases, migrations and edge functions from your agent

★ 2.9k · +6 this week

8.5 GitHub ↗

If your backend already runs on Supabase, this closes the loop between "the agent wrote a migration" and "the agent can see whether it applied cleanly" without you pasting schema dumps into chat.

Sentry MCP 🔌 MCP serverFreemium

Sentry's MCP server: pull errors, stack traces and issues into your agent

★ 898 · +37 this week

🔥 Sentry for Startups: up to $5,000 in credits (12-month expiry) for companies founded in the last 2 years with under $5M raised

8.2 Visit ↗

Wiring in error tracking means an agent debugging a regression can pull the actual stack trace and breadcrumbs instead of guessing from a description of the bug. Sentry also currently runs a startup credit program worth checking if you're pre-revenue — see /deals for the current terms.

Firecrawl MCP 🔌 MCP serverFreemium

Scrape, crawl and search the web as clean Markdown from your agent

★ 7.5k · +24 this week

🔥 Free plan: 1,000 credits every month, no card needed

8.5 Visit ↗

For anything that needs to read documentation or a competitor's site as part of a task, a scraping server saves the copy-paste round trip and gives the agent clean Markdown instead of raw HTML.

Cloud Agents for Parallel Work

Once local setup feels solid, Cursor's other lever is running agents somewhere other than your laptop. What used to be called Background Agents now ships as Cloud Agents — isolated virtual machines that run a full development environment independently of whether your machine is on. You can start one from Cursor Desktop (the "Cloud" option in the run dropdown), from cursor.com/agents in a browser, from the iOS app, or by triggering one from Slack, GitHub, Bitbucket or Linear.

Two things have to be true before a cloud agent can run against a repository. First, a Cursor account admin needs to have connected source control for the account — GitHub, GitLab, Bitbucket Cloud and Azure DevOps are all supported, and the agent needs read-write privileges on the repo and any submodules. Second, the environment itself needs configuring: either let the agent set it up on first run, save a snapshot once it's working, or define it explicitly with a Dockerfile referenced from .cursor/environment.json. Cursor's own docs are blunt about this being the highest-leverage step — a cloud agent that has to reinstall dependencies and guess at your test command every run is much less useful than one with a working environment already captured.

Cloud Agents require a paid Cursor plan, and usage is billed at API pricing for whichever model you select — a larger context window increases both token usage and cost, so it's worth setting a spend limit the first time you turn one on rather than after.

A Minimal First-Weekend Checklist

If you're setting up a new project from scratch, this is roughly the order that avoids backtracking:

Steps 1 through 4 are worth doing on every project regardless of team size; steps 5 and 6 only pay off once you're actually running tasks unattended, so there's no rush to get there on day one.

Common Mistakes That Undercut All of This

A few habits quietly cancel out the benefit of setting any of this up properly:

Marking every rule alwaysApply: true. It's tempting, since it guarantees the agent sees the rule — but stacking five or six always-on rules recreates the giant-system-prompt problem rules were supposed to fix. Reserve alwaysApply for genuinely universal context (stack, structure, non-negotiables) and let glob-matching or the agent's own judgment handle the rest. If a rule only matters in src/api/, a glob does the filtering for you instead of relying on the agent to skim past it in every other directory.

Committing real secrets into .cursor/mcp.json. Because the project-scoped config is meant to be checked into version control, it's easy to paste an API key straight into env and commit it without thinking. Use environment variable references or your existing secrets manager, and treat mcp.json the way you'd treat any other config file that's about to be pushed to a shared remote.

Turning on Cloud Agents without an environment snapshot. An agent that has to reinstall dependencies, guess at your test runner and figure out your lint command from scratch on every run burns time and API spend before it does anything useful. A few minutes spent letting the agent set up the environment once, then saving that as a snapshot or writing it into .cursor/environment.json, pays for itself the second run onward — and matters more to the effectiveness of a cloud agent than almost anything else in this setup.

Never setting a spend limit. Cloud Agents bill at API pricing per model, and a wide context window on a long-running task adds up faster than the equivalent local session would, since nothing is waiting on you to hit enter between turns. Set the limit before the first run, not after checking the bill.

The Takeaway

Cursor's defaults work fine for a quick edit, but the compounding value is in the files you check into the repo: rules that travel with the code instead of living in chat history, and an MCP config that gives the agent the same access to your systems that you have. Twenty minutes spent writing one good alwaysApply rule and wiring in the MCP server for whatever you're already using saves far more time over a project's life than tweaking prompts session to session. For the broader landscape of what else plugs into Cursor and other agents, the ecosystem page tracks which apps support which standards, and the glossary is a quick reference if any of the terminology here — MCP, rules, agent-selected — is new.