Add a referral program with Cursor
Cursor's agent uses project rules in .cursor/rules and MCP servers from .cursor/mcp.json. The RefRef rule applies when the agent decides it is relevant, or when you mention @refref.
Give Cursor the RefRef rules
The rules tell the agent where each part of a referral integration belongs: the landing script in the browser, one signup call where your backend creates the account, and the API key only on the server. Save it as .cursor/rules/refref.mdc.
Cursor attaches a project rule to the agent's context in one of four ways: always, by file glob, when the agent decides from the rule's description that it is relevant, or when you mention it. The RefRef rule uses the description, so Cursor loads it for signup and referral work and leaves it out of unrelated chats. Mention @refref in the prompt to be sure.
---
description: "RefRef referral tracking: landing script, signup call at account creation, server-only API key. Use when you add or change signup, referral, or invite code."
alwaysApply: false
---
# RefRef referral tracking
This app uses RefRef (https://refref.ai) for its referral program. Follow these rules when you add or change referral code.
## Configuration
- Server-only secrets: `REFREF_API_KEY` (a Workspace API key), `REFREF_PROJECT_ID`, and `REFREF_PROGRAM_ID`.
- `REFREF_API_URL` defaults to `https://api.refref.ai`, and `REFREF_ASSETS_URL` to `https://assets.refref.ai`. Read both from configuration, so that a Sandbox or local environment can change them.
- Never put `REFREF_API_KEY` in browser code, in a public variable (`NEXT_PUBLIC_*`, `VITE_*`), in a prompt, in a log, or in a commit.
- Every RefRef call is a backend `POST` with a JSON body that contains `projectId`, and the header `X-Api-Key`. The current schemas are at `GET $REFREF_API_URL/openapi`.The start of the file. Open the whole file.
Or fetch it from the command line: curl -fsSL --create-dirs https://refref.ai/agents/cursor/rules.md -o .cursor/rules/refref.mdc
Connect Cursor to RefRef MCP
Optional. With the MCP server, Cursor can read your Workspaces, Projects, and Programs, and prepare configuration changes for you to approve in the Console. It never sends signups: that is the app code from the rules. See the MCP reference for scopes and approvals.
Configuration: .cursor/mcp.json (project) or ~/.cursor/mcp.json (all projects)
{
"mcpServers": {
"refref": {
"url": "https://mcp.refref.ai/mcp"
}
}
}Sign in
Open Cursor Settings → MCP, find refref, and connect. Sign in with your RefRef Console account in the browser. In the Cursor CLI, agent mcp login refref does the same. The connection uses your Console sign-in, never a Workspace API key.
Check it
Cursor Settings → MCP shows refref with its tools; agent mcp list in the CLI.
- Cursor reads only .mdc files in .cursor/rules. A plain .md file there is ignored.
- Cursor also reads AGENTS.md, if you prefer one file for several agents.
1. Configure the Program through MCP
Optional. Needs the refref MCP server and a Console account with the owner or admin role.
Use the refref MCP server. Call get_workflow with workflow="configuration", then list_workspaces. Ask me to choose the Workspace, and use only the Sandbox Project that I confirm. Read its Programs and rules. Propose a referral Program that gives the referrer a reward when a referred person signs up. Ask me for the reward, the currency, and the limits; do not assume them. Return the proposal and its review link. Do not approve or apply it.2. Add referral tracking to the signup
The rehearsal ran this prompt with "the project instructions" in place of the rules file name, on a Node app whose tests use node --test.
Add RefRef referral tracking to the signup of this app. Follow the RefRef rules in @refref. Configuration comes from environment variables. Do not add dependencies. Add focused tests and run them.3. Review the change before you merge it
Run it in a new session, so that the agent reads the diff with fresh context.
Review the RefRef integration in the current diff against @refref. Check each item of "Tests to write" and "Do not". Confirm that the signup is sent once, only where the account is created, and that REFREF_API_KEY never reaches the browser. List each problem with its file and line. Change nothing.Set REFREF_API_KEY, REFREF_PROJECT_ID, and REFREF_PROGRAM_ID in your backend environment. The integration reference has each call, and the auth recipes cover email verification, magic links, and hosted login.
What we ran, and what happened
Some checks have not run yet. Treat the open steps as a guide to verify yourself, and record your own results.
- pendingConfigure the MCP server and sign in with Cursor
- Not run: the Cursor CLI (agent) is not installed on the rehearsal machine, and the editor flow needs a person at the settings page.
- pendingPrompt 2 and the rules file produce a working signup integration
- Not run. Run prompt 2 with .cursor/rules/refref.mdc on a test app, then follow A's link as B and check the referral, a repeated sign-in, and the browser bundle.
01Why is the rule not always applied?
Referral code is a small part of most codebases, so the rule has a description and alwaysApply: false. The agent loads it when the task is about signup or referrals, and you can force it with @refref. Set alwaysApply: true if you prefer.
02Can I use a plain .md file in .cursor/rules?
No. Cursor reads only .mdc files there. Keep the frontmatter of the downloaded refref.mdc, or put the text in AGENTS.md instead.
Official references
Start with a Sandbox Project
Create a RefRef account, add a Project, and get the keys that the Cursor prompts need. Sandbox data never mixes with live data.