Cursor: technical tutorial

By Ivo Donker · October 28, 2026 — created with AI assistance (writer: DeepSeek V4.1 Flash; critic: Gemini 3.8 Flash)

Cursor: Review Install & set up News Technical tutorial

As of September 2026, compiled from our own notes and news archive; text machine-generated and editorially checked. Check versions and commands in the official documentation.

This tutorial is for developers who want to get more out of Cursor than the chat: rules with glob scoping, MCP servers with variables and OAuth, the command-line agent in scripts and CI, and control over costs and privacy. All file names and keys have been checked against the official documentation (as of September 2026).

Rules: four types

Cursor recognises four types of instructions:

Project rules in .cursor/rules/, as .mdc files. They are kept in version control and apply to this codebase.
AGENTS.md in your project: a simple alternative in plain markdown, which other coding agents also read.
User rules in your settings: apply to all your projects.
Team rules, managed via the dashboard (Team and Enterprise plans).

If you want Claude Code, Codex and Cursor to follow the same instructions, put the shared rules in AGENTS.md and keep the Cursor-specific refinement in .cursor/rules/.

The .mdc format

A project rule is markdown with frontmatter. Ordinary .md files in .cursor/rules/ are ignored.

---
description: "API-handlers: validatie en foutafhandeling"
globs: src/api/**/*.ts
alwaysApply: false
---
- Valideer elke request-body met zod voordat je hem gebruikt.
- Geef fouten terug in het formaat `{ error: { code, message } }`.
- Log nooit volledige request-bodies; ze kunnen persoonsgegevens bevatten.

The three fields together determine when a rule is included:

Always Apply (alwaysApply: true): in every session. Keep this short, because it costs context on every question.
Apply Intelligently (only a description): the agent decides based on the description. So write the description as a criterion, not as a title.
Apply to Specific Files (globs): as soon as files matching the pattern are involved.
Apply Manually: only when you mention the rule in the chat with @.

A practical pattern: one short rule with alwaysApply: true for the basics (stack, test and build commands), and otherwise rules with globs for each part of the codebase.

MCP servers

You configure MCP servers in JSON: per project in .cursor/mcp.json, or globally in ~/.cursor/mcp.json.

A local server (stdio):

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "mijn-db-mcp"],
      "env": { "DATABASE_URL": "${env:DATABASE_URL}" }
    }
  }
}

A remote server (Streamable HTTP or SSE):

{
  "mcpServers": {
    "docs": {
      "url": "https://docs.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:DOCS_TOKEN}" }
    }
  }
}

You can use variables in values, so that no key ends up in your repository:

${env:NAAM}: an environment variable.
${userHome}: your home directory.
${workspaceFolder}: the root of the project.
${workspaceFolderBasename}: the name of the project.
${pathSeparator}: the operating system's path separator.

For servers with fixed OAuth credentials, you add an auth object:

{
  "mcpServers": {
    "crm": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}",
        "scopes": ["read"]
      }
    }
  }
}

Register http://localhost:8787/callback with the provider as a redirect URL for the desktop app, and https://www.cursor.com/agents/mcp/oauth/callback for the web version and cloud agents.

The command-line agent in scripts and CI

Install with curl https://cursor.com/install -fsS | bash; the program is called agent. With -p (or --print) it runs without interaction.

export CURSOR_API_KEY="..."   # uit je Cursor-dashboard, als secret in CI

# alleen analyseren
agent -p "Wat doet deze codebase?"

# wijzigingen doorvoeren zonder bevestiging
agent -p --force "Zet deze module om naar moderne ES-syntax"

# gestructureerde uitvoer voor verdere verwerking
agent -p --output-format json "Geef een lijst van ongebruikte exports"

--output-format supports text, json and stream-json. The latter provides progress in real time, useful for long tasks in CI logs.
--force (also --yolo) lets the agent modify files without asking. Use it only in a clean checkout or container, and have a human review the diff.
--model selects the model. Without that flag, the agent uses your default setting.

A simple CI step that stores a review as an artefact:

agent -p --output-format json \
  "Beoordeel de wijzigingen ten opzichte van main op bugs en beveiligingsrisico's" \
  > review.json

Managing costs

As of September 2026, Cursor uses two monthly allowances:

Cursor models: Cursor's own Composer 2.5 and the Grok models, with generous included usage.
Other models: Claude, GPT, Gemini and the like, billed at API rates. In Auto mode, an additional $0.25 per million tokens applies.

What helps:

For routine work, use Composer or Auto in Cost mode. Only choose an expensive model for difficult tasks.
Keep alwaysApply rules short: they are included with every question.
If you exceed your allowance, you can buy additional usage at API rates or take a larger plan. Cursor never silently degrades quality.

Privacy and teams

Privacy Mode ensures that your code is not used for training and applies with zero data retention. Exceptions are your own API keys and models for which the provider itself must retain data. On Teams and Enterprise, Privacy Mode is on by default and an administrator can enforce it.
Keep sensitive folders (secrets, customer data) out of reach with a .cursorignore in the root of your project; it works with the same syntax as .gitignore. A rule in .cursor/rules/ is only a request to the model, not an enforced block.

Troubleshooting

A rule is not applied: the file has the .md extension instead of .mdc, or the globs do not match the files in your context. Mention the rule with @ to test.
MCP server does not start: check whether the variable behind ${env:...} exists in the environment in which Cursor runs. Apps that start from the Dock or the start menu do not always see the variables from your shell profile.
OAuth error with an external server: the redirect URL at the provider does not match the environment (desktop or web).
CLI agent asks for login in CI: CURSOR_API_KEY is not set or not passed to the job as a secret.

Documentation: cursor.com/docs.