Cursor Rules File Location, AGENTS.md, MCP & Permissions Guide

Cursor project rules live in .cursor/rules/ as .mdc files with description, globs and alwaysApply frontmatter. Cursor also reads AGENTS.md in the project root and in subdirectories, and User Rules from Customize → Rules. MCP servers go in .cursor/mcp.json or ~/.cursor/mcp.json, hooks in .cursor/hooks.json. Run Modes (Auto-review, Allowlist, Run Everything) plus sandbox.json control what the agent may run. You pay with a Cursor plan or bring your own API keys; Claude and ChatGPT subscriptions are not a login option.

Cursor at a glance

Global instructions	✓ Yes User Rules in Customize → Rules (stored in Cursor, not a file); Team Rules from the dashboard
Project instructions	✓ Yes `.cursor/rules/*.mdc` (frontmatter: description, globs, alwaysApply), `AGENTS.md`. Precedence Team → Project → User
Nested / subfolder	✓ Yes Nested `AGENTS.md` in any subdirectory; `.cursor/rules/` subfolders
AGENTS.md	✓ Yes Root and nested AGENTS.md, combined with parents
Skills (SKILL.md)	✓ Yes `.cursor/skills/`, `.agents/skills/`, `~/.cursor/skills/`, `~/.agents/skills/`; also `.claude/skills/` and `.codex/skills/` for compatibility
MCP config	✓ Yes `.cursor/mcp.json` (project) and `~/.cursor/mcp.json` (global), `mcpServers` object
Permissions / allowlist	✓ Yes IDE Run Modes: Auto-review, Allowlist, Run Everything; `permissions.json` steers Auto-review. CLI: `permissions.allow`/`deny` with `Shell()`, `Read()`, `Write()`, `WebFetch()` in `~/.cursor/cli-config.json` or `.cursor/cli.json`
Sandbox	✓ Yes Terminal sandbox; configure with `~/.cursor/sandbox.json` or `.cursor/sandbox.json`; network blocked by default inside it
Hooks	✓ Yes `.cursor/hooks.json` and `~/.cursor/hooks.json`: preToolUse, beforeShellExecution, afterFileEdit and more; can load Claude Code hooks
Claude Pro/Max login	✕ No Not a login option; add an Anthropic API key instead
ChatGPT Plus/Pro login	✕ No Not a login option; add an OpenAI API key instead
API key / own plan	✓ Yes BYOK for OpenAI, Anthropic, Google, Azure OpenAI, AWS Bedrock (chat models only; Tab stays on Cursor models)

Exact file paths

Path	Scope	What it does
`.cursor/rules/*.mdc`	Project	Project rules with description / globs / alwaysApply
`AGENTS.md (root and subfolders)`	Project	Plain-markdown instructions, nested files supported
`Customize → Rules`	User	User Rules (global preferences)
`.cursor/mcp.json / ~/.cursor/mcp.json`	Project / user	MCP servers
`.cursor/hooks.json / ~/.cursor/hooks.json`	Project / user	Agent hooks (project hooks also run in cloud agents)
`.cursor/permissions.json / ~/.cursor/permissions.json`	Project / user	Auto-review allow/block instructions
`.cursor/sandbox.json / ~/.cursor/sandbox.json`	Project / user	Sandbox network and path rules
`.cursor/cli.json / ~/.cursor/cli-config.json`	Project / user	Cursor CLI permission tokens
`.cursor/skills/<name>/SKILL.md`	Project	Skills (also .agents/skills, ~/.cursor/skills)

Using a shared AGENTS.md with Cursor

Native (root and nested). Add .cursor/rules/*.mdc only for glob-scoped rules. See one AGENTS.md for every agent, or generate one with the AGENTS.md generator.

Copy-paste examples

Always-on project rule

File: .cursor/rules/project.mdc

---
description: Core project conventions
alwaysApply: true
---

- Use pnpm, never npm or yarn.
- Run `pnpm test` before finishing a task.
- API handlers live in `src/api/handlers/`.

Glob-scoped rule

File: .cursor/rules/react.mdc

---
description: React component guidelines
globs: src/components/**/*.tsx
alwaysApply: false
---

Use function components and hooks. No class components.

Project MCP server

File: .cursor/mcp.json

{
  "mcpServers": {
    "postgres-readonly": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://readonly@localhost/app"]
    }
  }
}

Safe permissions preset

Safe Cursor CLI permissions (deny destructive commands and secrets)

File: .cursor/cli.json

{
  "permissions": {
    "allow": [
      "Shell(ls)",
      "Shell(git:status*)",
      "Shell(git:diff*)",
      "Read(src/**)",
      "Write(src/**)"
    ],
    "deny": [
      "Shell(rm)",
      "Shell(sudo)",
      "Shell(git:push*)",
      "Read(.env*)",
      "Write(**/.env*)",
      "Write(**/*.key)"
    ]
  }
}

Shell() matches the first token of the command; command:args globs (e.g. git:push*) narrow it. Deny rules take precedence over allow rules. In the IDE, pick the Allowlist or Auto-review Run Mode instead of Run Everything and keep the sandbox on; Cursor says Auto-review is not a security boundary.

Gotchas

A plain .md file in .cursor/rules/ is ignored by the rules system; project rules must use the .mdc extension. Use AGENTS.md if you want plain markdown.
User Rules are stored in Cursor settings, not in a file you can commit. Put team rules in .cursor/rules/ or AGENTS.md.
Custom API keys only work for chat models; Tab completion keeps using Cursor's own models.
User-level hooks (~/.cursor/hooks.json) do not run in cloud agents; only the repo's .cursor/hooks.json does.
Legacy .cursorrules is not described in the current rules docs; migrate it to .cursor/rules/*.mdc or AGENTS.md.

FAQ

Where is the Cursor rules file?

Project rules are .mdc files in .cursor/rules/ at the repository root (subfolders allowed). User Rules live in Customize → Rules. Cursor also reads AGENTS.md in the root and in subdirectories.

Does Cursor support AGENTS.md?

Yes. Cursor reads AGENTS.md in the project root and in subdirectories; nested files are combined with their parents, more specific instructions taking precedence.

Where is the Cursor MCP config?

.cursor/mcp.json in the project for project servers and ~/.cursor/mcp.json for servers available in every project. Both use an mcpServers object.

Can I use my Claude or ChatGPT subscription in Cursor?

No. Cursor bills through its own plans. You can add your own Anthropic, OpenAI, Google, Azure or Bedrock API key for chat models.

Sources

Checked against these official pages on 2026-10-12. Cells marked "Not documented" mean we could not find the behaviour in these docs; it may still exist.

Cursor configuration guide: instruction files, MCP, permissions