How to give Cursor context about your project

The failure looks like this. You ask Cursor to add a plan gate to the billing page. It reads the code, finds a customer object, and writes a check on customer.tier. There is no tier. The entity has plan_id. The spec that says so is in Notion, or in a Slack thread, or in your head. Cursor never had it.

Cursor builds from what is in its context window: the open files, the rules it loaded, whatever you typed or attached. Everything else is a guess. Giving Cursor context about your project means deciding where the truth about your product lives and how the agent reaches it on every session, not only the one where you remembered to paste.

There are four ways to do that. The first three hold instructions and access. Only the fourth holds the spec itself. They stack: most teams end up with two, rules for how they code and something heavier for what they are building.

1. 01

   .cursorrules / .cursor/rules

   Standing instructions: conventions, commands, what never to do.

2. 02

   @Docs and pasting

   Hand the agent a document. Lasts one session, or one crawled URL.

3. 03

   .cursor/mcp.json

   A live source the agent queries mid-task: a schema, a tracker, a wiki.

4. 04

   ContextsBase over MCP

   The spec, data model, and test cases themselves, published.

Rules are plain text Cursor loads into the context window before the agent starts. The legacy form is a single .cursorrules file in the repository root. The current form is a .cursor/rules folder of .mdc files, each with frontmatter that decides when it attaches. Cursor calls these Project Rules.

---
description: Product rules for the billing area
globs: ["src/billing/**", "e2e/billing/**"]
alwaysApply: false
---

- Plans are free and premium. The column is users.plan_id.
  There is no tier field anywhere. Do not add one.
- Password reset links expire in 15 minutes and work once.
- Every business rule gets a Playwright test in e2e/ before the PR.
- Never call Stripe from a component. Go through lib/billing.

Rules are the right home for conventions: the framework, the folder layout, how to run tests, what never to do. Keep each one under about fifty lines and scoped with globs. A rule that is always on and three hundred lines long crowds out the code the agent should be reading.

The legacy .cursorrules file

# Legacy single file at the repository root
Next.js 14 app with Tailwind. Package manager is pnpm.
Plans are free and premium. The column is users.plan_id, not tier.
Run "pnpm test:e2e" before you open a PR.

The fastest way to give Cursor context is to hand it the document. Paste the spec into the chat, attach a file with @Files, or add a URL under @Docs so Cursor crawls and indexes it. For a library’s public reference, @Docs is excellent. For your own product spec, it has a shelf life of one conversation.

The mockup is the common case. The spec was pasted yesterday. Today is a new session, the paste is gone, and the agent does the reasonable thing: it infers the rules from the code. Inference is how you get customer.tier. Nothing in the repository contradicts it, so nothing stops it.

@Docs does persist, because Cursor keeps the index. But it only crawls public URLs, it stores the page as prose, and it has no idea which feature you are building next. It answers “what does this library do” well and “what should this app do” poorly.

MCP, the Model Context Protocol, lets Cursor call tools on a server you point it at. You register servers in .cursor/mcp.json for one project, or ~/.cursor/mcp.json for all of them. A server can run locally as a command or remotely over HTTP. Once enabled under Cursor Settings, MCP, its tools appear in Agent mode and the agent decides when to call them.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/app"
      ]
    },
    "internal-docs": {
      "url": "https://docs.internal.example.com/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
    }
  }
}

This is a real step up. The agent now pulls context on demand instead of relying on what was pasted. Point it at a Postgres server and it can read the schema instead of guessing at customer.tier. Point it at an internal docs server and it can fetch the page it needs.

What a generic MCP server gives you

Most off-the-shelf MCP servers are adapters: a database, a file tree, a wiki, an issue tracker. They give the agent access to a system it could not otherwise reach. Access is not structure. The agent can now read every column in users. It still has to work out what the product is supposed to do with them, and the server itself is yours to run, secure, and keep online.

Method 4 is method 3 with the right thing on the other end. Instead of a raw source, the MCP server holds the product itself as structured objects: features with business rules, entities with fields and foreign keys, flows, test cases written as Given, When, Then, and iterations that order the work. That is what ContextsBase is: context infrastructure for coding agents. You write the knowledge once. Cursor builds from it every session.

The instruction is one line: Implement iteration I-1. Cursor calls next_iteration_item, which claims the next unstarted feature and returns everything in one bundle: the spec and its rules, the entities it touches, the flow, the test cases, and the theme tokens. It builds, turns T-7 and T-8 into Playwright tests, and calls record_test_automation and record_feature_implementation. The feature flips to Implemented. Nobody pasted anything.

Connect Cursor

Create a project, publish at least one feature, and generate an MCP token under the project’s Agents tab. Then add the server to .cursor/mcp.json:

{
  "mcpServers": {
    "contextsbase": {
      "url": "https://app.contextsbase.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer mcp_live_••••••••••••••••••••••••"
      }
    }
  }
}

Enable the server under Cursor Settings, MCP. In Agent mode you should see five tools:

Keep your .cursor/rules for conventions. Delete the spec you pasted into them. Each implementation record carries a fingerprint of the spec it was built from, so when the feature changes later the record turns Outdated instead of silently drifting.

Setup time is for a working first version. “Survives new sessions” means the agent has the context tomorrow without you doing anything. “Agent can write back” means the method records what was built, not only what was asked.

Start with rules. Move up when you hit one of these.

1. 01

   Stay on rules

   While the project is yours alone and the product fits in a few sentences. Add @Docs for the libraries you lean on.

2. 02

   Add an MCP server

   When the agent needs a live source: the real schema, the issue tracker, recent logs. Prose in a rules file cannot keep up.

3. 03

   Move to a structured knowledge base

   The second time you paste the same spec, the first time the agent invents a field, or the day a second person or a second agent starts working the same backlog.

4. 04

   Keep them layered

   Rules for how you code. ContextsBase for what you are building. A raw MCP server for data only the database knows.

The same four levels exist for Claude Code, with CLAUDE.md in place of rules and .mcp.json in place of .cursor/mcp.json. That guide is How to give Claude Code context about your project. If you are weighing rules files against a knowledge base specifically, the Cursor rules alternative page puts them side by side.