Add a referral program with Claude Code
Claude Code reads CLAUDE.md at the start of each session and connects to remote MCP servers over HTTP. Give it both, and it can read your referral configuration and write the signup tracking in your codebase.
Give Claude Code 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 CLAUDE.md in the repository root, or add its text to your existing CLAUDE.md.
Claude Code loads CLAUDE.md from the repository root, and from parent folders, at the start of every session, so the rules apply to each prompt without a mention. Headless runs with claude -p read it too, which is how the rehearsal ran. Keep the rules in the root file, or import a separate file with an @path line, so that a subagent that starts in a subfolder still sees them.
# 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 https://refref.ai/agents/claude-code/rules.md >> CLAUDE.md (>> appends to an existing file)
Connect Claude Code to RefRef MCP
Optional. With the MCP server, Claude Code 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: .mcp.json (project scope, shared in the repository)
{
"mcpServers": {
"refref": {
"type": "http",
"url": "https://mcp.refref.ai/mcp"
}
}
}Or with the CLI
claude mcp add --transport http --scope project refref https://mcp.refref.ai/mcpSign in
Run /mcp in Claude Code, select refref, and sign in with your RefRef Console account in the browser. From a terminal, claude mcp login refref does the same. The connection uses your Console sign-in, never a Workspace API key.
Check it
claude mcp get refref
- Keep "type": "http". An entry with a url and no type is read as a local command and fails.
- Claude Code asks you to approve a project server from .mcp.json once. Use --scope local to keep the server out of the repository.
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 CLAUDE.md. 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 CLAUDE.md. 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
Each check below ran end to end. A Reward that the journey earns is an accounting result, not a delivered payment.
- passed · 2026-10-20The MCP configuration is the one that Claude Code writes
- claude mcp add --transport http --scope project refref https://mcp.refref.ai/mcp (Claude Code 2.1.304) wrote exactly the .mcp.json shown above.
- passed · 2026-10-20OAuth sign-in and a read tool call against a RefRef stack
- Against a disposable RefRef stack: claude mcp login --no-browser, consent in Chrome as a Workspace owner, and the redirect URL pasted back; claude mcp get then showed the server as connected. A headless claude -p session, allowed only list_workspaces and list_projects, listed both Workspaces with the Live and Sandbox Projects. Changed nothing.
- passed · 2026-10-20Prompt 2 and the rules file produce a working signup integration
- Claude Code 2.1.304 ran prompt 2 headless (acceptEdits, file tools and node --test only) with the rules as CLAUDE.md, on a bare Node signup app. It added refref.mjs, a signup call in the account-creation route with the refref_handle cookie, retries with backoff only for 5xx, 408, and 429 answers, and five tests in test/refref-signup.test.mjs that match the rules' test list. Against a disposable RefRef stack: B followed A's link in Chrome and signed up, and the referral named A as referrer and B as referee; B's next sign-in sent no second signup; an organic signup made no referral; no page contained the API key; the signup succeeded with RefRef unreachable.
01Can I keep the RefRef rules out of my main CLAUDE.md?
Yes. Save the rules as a separate file, for example docs/refref.md, and add the line @docs/refref.md to CLAUDE.md. Claude Code imports the file into every session.
02Does Claude Code need permission prompts for this work?
It edits files and runs your tests. In the rehearsal, Claude Code ran in acceptEdits mode with only file tools and node --test allowed, which was enough to write the integration and its tests.
Official references
Start with a Sandbox Project
Create a RefRef account, add a Project, and get the keys that the Claude Code prompts need. Sandbox data never mixes with live data.