Building AI Agents with Cursor

Building AI agents with Cursor is less about writing agent framework code and more about configuring Cursor's built-in agentic machinery to do real work. Cursor is an AI-native code editor built on VS Code, and its Agent mode gives the model the ability to read files, run terminal commands, search the codebase, and iterate on output, all inside your normal editor workflow. That's the agentic loop, surfaced as an editor feature rather than a Python script.

This tutorial covers what's actually useful: Agent mode configuration, connecting external tools via the Model Context Protocol (MCP), setting up background agents for long-running tasks, and the failure modes we've hit at Laxaar while building production workflows on top of Cursor.

Prerequisites: Cursor 0.45+ installed, a project open in Cursor, and an Anthropic or OpenAI API key configured in Cursor settings.

What you'll build

• Configure Cursor Agent mode for your project
• Write a .cursor/rules file that shapes agent behavior
• Connect an MCP tool server to extend what the agent can do
• Run a multi-step agent task end-to-end
• Set up a background agent for long-running work

Step 1: Configure Agent mode

Agent mode is Cursor's term for the agentic loop: the model can call tools, observe results, and keep working without you manually approving each step. It's on by default in the Composer panel (Cmd+I on Mac, Ctrl+I on Windows).

Open Cursor Settings (Cmd+,) and confirm:

• Model: Claude Sonnet 4.5 or Claude Opus 4 for complex tasks. Cursor proxies to Anthropic by default; you can also bring your own API key under "API Keys."
• Agent auto-run: Set to "Auto" if you want the agent to run terminal commands without prompting. "Ask" is safer while you're learning the tool.
• Context window: Leave at maximum. Agent tasks often need large context.

One setting that's easy to miss: "Include recent terminal output in context" under Agent settings. Turn this on. It lets the agent see command failures without you having to paste them back in.

Create a .cursor directory at your project root — Cursor picks up configuration from here automatically:

mkdir -p .cursor

Step 2: Write cursor rules

.cursor/rules (or the legacy .cursorrules file) is where you tell the agent how to behave in your project. Think of it as a persistent system prompt that applies to every Composer session. This is one of the most underused features in Cursor — most developers leave it blank and then wonder why the agent makes inconsistent decisions.

Here's a rules file for a Next.js TypeScript project:

# Project conventions
- This is a Next.js 15 App Router project. Always use the App Router file conventions (page.tsx, layout.tsx, loading.tsx).
- TypeScript strict mode is enabled. Never use `any` without a comment explaining why.
- State management: use React Server Components by default. Only add client-side state with `useState` when the component genuinely needs interactivity.
- Styling: Tailwind CSS only. No inline styles, no CSS modules unless the component needs CSS animations.
- Testing: Vitest + React Testing Library. New components get a test file.

# Agent behavior
- Before editing a file, read it first to understand the existing structure.
- After editing, run `npm run typecheck` and fix any errors before considering the task done.
- Don't install packages without checking package.json first to see if a suitable package already exists.
- If a task is ambiguous, ask one clarifying question before proceeding.

Short, declarative rules outperform long prose instructions. The agent reads this on every turn, so every line competes for context space.

Step 3: Connect an MCP server

MCP (Model Context Protocol) is an open standard for connecting LLMs to external tools. Cursor supports MCP natively, which means you can give the agent access to databases, APIs, file systems, and services beyond what the editor provides by default.

Here's how to connect a filesystem MCP server that lets the agent operate on a directory outside your project:

# Install the reference filesystem MCP server
npm install -g @modelcontextprotocol/server-filesystem

Add the server to .cursor/mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents/project-data"
      ]
    }
  }
}

Restart Cursor. Open Composer and type:

List all CSV files in the project-data directory and tell me how many rows each one has.

The agent now has access to the filesystem MCP tools and can read the directory, iterate over files, and report back — without you writing any code.

For a more practical example, here's connecting to a PostgreSQL database via MCP:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

With this connected, you can ask the agent to write and run queries, inspect schemas, and generate migration files — all from a natural-language prompt in Composer.

At Laxaar, we've used MCP to connect agents to internal APIs and data stores on client projects. The pattern is consistent: define the server in mcp.json, confirm the agent can call it in a test session, then rely on it in the real workflow.

Step 4: Run a multi-step agent task

Let's run a real agent task that uses multiple tools. Open Composer (Cmd+I) and switch to Agent mode if it isn't already selected. Enter this task:

Audit this project for dead code:
1. Find all exported functions and components in src/
2. Find all imports across the project
3. List any exports that are never imported
4. Create a file called dead-code-report.md with your findings

Watch what the agent does:

1. It runs find or uses Cursor's codebase search to locate exported symbols
2. It greps for import statements across all files
3. It cross-references the two lists
4. It writes the markdown report

The agent won't always take the most efficient path — it might read more files than necessary, or try a shell command that fails and then adjust. That's expected. What you're watching for is whether it recovers from failures gracefully and produces correct output at the end.

If the agent gets stuck in a loop or starts producing wrong output, use the "Stop" button in Composer and add a clarifying instruction. Don't let a confused agent run for 20+ steps — the cost in tokens and time adds up fast.

Expected terminal output during the run:

> find src -name "*.ts" -o -name "*.tsx"
src/components/Button.tsx
src/components/Modal.tsx
...

> grep -r "from './Modal'" src/
src/pages/Settings.tsx:import Modal from './Modal'
...

Step 5: Background agents

Background agents in Cursor run tasks asynchronously while you keep working. They're useful for long-running operations: running a full test suite, performing a large-scale refactor, or processing a batch of files.

To start a background agent:

1. Open the Background Agents panel (Cmd+Shift+A or via the sidebar icon)
2. Click "New Agent"
3. Describe the task

Run the full test suite with `npm test`, collect all failing tests, and for each failure:
- Read the failing test file
- Read the source file it tests
- Fix the bug in the source file (not the test)
- Confirm the fix passes by re-running that specific test
Report a summary when done.

Background agents use the same model and tool access as foreground Composer sessions. The difference is that they don't block your editor. You can switch files, write code, and check back on the agent progress when it finishes.

One real constraint: background agents can't interact with UI elements. If your tests require a browser or a running dev server, the agent will fail to start those processes. Make sure the task can run entirely in the terminal.

Here's a .cursor/rules addition that helps background agents behave consistently:

# Background agent behavior
- When running tests, always use --reporter=verbose so failures include full stack traces.
- Don't modify test files. If a test is wrong, note it in the report but don't change it.
- After each file edit, run `npm run typecheck -- --noEmit` to catch type errors immediately.

Common pitfalls

Agent rewrites files you didn't want touched. Cursor's agent can edit any file in your project. If it decides a refactor requires changing 15 files, it will. Use .cursor/rules to restrict scope: "Only edit files in src/components unless I explicitly ask you to change something else."

MCP server not connecting. Check that the server binary is installed globally and that mcp.json is in .cursor/, not the project root. Cursor only looks in .cursor/. Restart Cursor after every mcp.json change.

Agent ignores .cursor/rules. This happens when Composer is in "Chat" mode instead of "Agent" mode. Cursor Rules apply in both, but tool use only works in Agent mode. Also check that the file is named rules (no extension) inside .cursor/.

Context window fills up mid-task. Long tasks accumulate a lot of history. If the agent starts producing obviously wrong output halfway through a big task, start a fresh Composer session and paste in only the relevant context. Don't try to salvage a corrupted session.

Frequently Asked Questions

Does Cursor use my code for training?

By default, Cursor doesn't use your code to train models. Privacy mode (enabled in Settings) ensures no code is stored on Cursor's servers. Check their current privacy policy at cursor.com for the latest — policies change, and you should verify before using Cursor on client codebases with data restrictions.

Can I use my own Anthropic API key instead of Cursor's proxy?

Yes. Under Settings > API Keys, add your ANTHROPIC_API_KEY. You'll be billed directly by Anthropic at API rates, which is often cheaper if you use Cursor heavily. Cursor's Pro plan includes a usage quota; beyond that, bringing your own key is more economical.

How does Cursor Agent compare to Claude Code (the claude CLI)?

Cursor Agent is editor-native: it sees your open files, understands your workspace structure, and integrates with your editor UI. The claude CLI is terminal-native: it's more scriptable, easier to run in CI, and better for headless automation. For interactive development, Cursor is faster. For scripted or CI workflows, Claude Code wins.

What's the best model for agent tasks in Cursor?

Claude Sonnet 4.5 for most tasks — it's fast and handles multi-step reasoning well. Claude Opus 4 for complex architectural decisions or working with unfamiliar, large codebases. Don't use Haiku for agent tasks; it struggles with multi-step tool use.

How do I prevent the agent from running commands I don't want?

Set Agent auto-run to "Ask" in settings. This makes the agent request approval before running each terminal command. It's slower but lets you stay in the loop on destructive operations. For team projects, also add a .cursor/rules entry listing which commands are off-limits.

Cursor is a capable foundation for agentic coding workflows, but getting reliable results takes real configuration work. The Laxaar team helps engineering teams set up and optimize their AI-assisted workflows — talk to us about your project or see how we approach agentic development.