Configure Cursor Rules to enforce project conventions, use codebase indexing for semantic search, and connect MCP servers to extend Cursor's capabilities.
Cursor Rules let you set persistent instructions that apply to every chat and Agent session in your project. They are the equivalent of giving Cursor a standing briefing about how your team writes code.
Rules are stored in .cursor/rules/ as Markdown files. You can create as many rule files as you need, organized by topic.
Create a .cursor/rules/general.md file in your project root:
# Project Rules
## Technology Stack
- Framework: Next.js 15 with App Router
- Styling: Tailwind CSS v4 (no tailwind.config.js)
- Database: Drizzle ORM with Postgres
- Auth: Better Auth
## Coding Conventions
- Use `const` and arrow functions for components
- Always use TypeScript strict mode — no `any`
- Co-locate component tests in `__tests__/` adjacent to the component
- Import order: React → external libraries → internal modules
## Do Not
- Do not use `useEffect` for data fetching — use React Server Components or TanStack Query
- Do not add barrel index files (no `components/index.ts`)Cursor supports three rule types:
| Type | File location | When it applies |
|---|---|---|
| Always | .cursor/rules/*.md | Every chat and Agent request |
| Auto | .cursor/rules/*.md with globs frontmatter | Only when matching files are open |
| Manual | Referenced via @rules/filename in chat | Only when you explicitly mention it |
For auto-applied rules, add a frontmatter glob:
---
globs: ["**/*.test.ts", "**/*.spec.ts"]
---
# Test File Rules
Always use Vitest. Mock external services with `vi.mock()`.
Use `describe` blocks for grouping and `it` for individual cases.This rule only activates when you are working on test files.
Rules are read on every request and count toward your context window. Keep rules concise and focused — avoid adding reference documentation or large examples directly in rule files.
When you open a project, Cursor builds a semantic index of your code. This index powers the @codebase search capability in Chat.
In Chat, use @codebase followed by your question to search across all indexed files:
@codebase How does this app handle pagination?
Cursor searches the index semantically — it finds pagination-related code even if the variable names don't literally include the word "pagination."
You can also use @codebase in Agent mode to let Cursor autonomously explore the codebase as it plans its approach:
@codebase Refactor all API calls to use the centralized httpClient utility
Agent will scan the codebase, find every API call pattern, and rewrite them.
The index lives locally on your machine and is not sent to any server until you make a chat request.
Very large repositories (100k+ files) may have slower or incomplete indexing. Use .cursorignore (same syntax as .gitignore) to exclude node_modules, build outputs, and generated files from the index.
Create .cursorignore in your project root to exclude files from the index:
node_modules/
.next/
dist/
*.lock
*.log
Model Context Protocol (MCP) is an open standard that lets you connect external tools and data sources to Cursor. Once connected, Cursor's Agent mode can call these tools as part of its workflow.
Cursor ships with several built-in MCP integrations:
MCP servers are configured in .cursor/mcp.json:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
}
}
}Once an MCP server is configured, you can ask natural language questions in Chat and Agent will use the server's tools to answer them — querying a database, reading GitHub issues, or fetching external data as part of a larger task.
Rules give Cursor persistent project-specific instructions. Codebase indexing enables semantic search across your entire project. MCP servers extend Cursor with external data sources and tools. Together these three make Cursor deeply aware of your project context and capable of working with your full development environment. Combine them for the most productive agentic workflows.