Cursor Setup

This page does one thing: get CodeLoop to trigger automatically, on every chat, in every project you open in Cursor — without you remembering to ask. It takes about 90 seconds.

Prefer zero-touch? Install the Cursor extension— on every Cursor open, the extension writes a project rule to <workspace>/.cursor/rules/codeloop.mdc with alwaysApply: true, so step 3 below (the User-Rule paste) is no longer required. The MCP server registration and codeloop init still happen via the CLI as below. Install once with npx codeloop@latest install-cursor-extension.

The User Rule (copy this exactly)

This is the rule that turns CodeLoop from “installed” into “always running”. Paste it once into Cursor's User Rules field and it applies to every project you open from then on.

After EVERY code change, you MUST call codeloop_verify from the CodeLoop MCP server. If .codeloop/config.json does not exist, call codeloop_init_project FIRST. After verify: diagnose failures with codeloop_diagnose, fix, re-verify until codeloop_gate_check returns ready_for_review with confidence >= 94%. For UI projects: screenshots + video capture are MANDATORY. Never declare a task complete without passing codeloop_gate_check.

Why a User Rule and not a project file? Cursor stores User Rules in an internal database that loads on every chat, in every project, automatically. A project-level .cursor/rules/codeloop.mdc only covers that one project. The User Rule is the only way to guarantee always-on behaviour everywhere.

Per-project setup (skipping the global write)

By default npx codeloop initwrites both project files and global activation files. If you're on a CI runner or a multi-tenant box where touching ~/.cursor/mcp.json is undesirable, opt out of the global half with --skip-global:

cd your-project
npx codeloop init --skip-global

That writes only .cursor/mcp.json, .cursor/rules/*.mdc, and .codeloop/config.json in the current repo. CodeLoop will trigger in this workspace but no global state changes.

Manual MCP configuration (advanced)

If you can't run codeloop init for some reason (locked-down dev box, custom path, etc.), the file below is what init writes. Drop it in either .cursor/mcp.json (project-only) or ~/.cursor/mcp.json (global — same effect as init --global):

{
  "mcpServers": {
    "codeloop": {
      "command": "npx",
      "args": ["-y", "codeloop-mcp-server@latest"],
      "env": {
        "CODELOOP_API_KEY": "cl_live_your_key_here"
      }
    }
  }
}

The @latesttag is what makes the MCP server auto-update on every Cursor restart — npx re-resolves the dist-tag against npm each time Cursor spawns the server. Don't pin a specific version unless you intentionally want to.

Manual MCP only handles the “available” half. You still need the User Rule paste from the activation chain above — otherwise the agent has the tools but never calls them.

Rule Files

CodeLoop creates rule files in .cursor/rules/ that guide the AI agent to use CodeLoop tools at the right moments:

core.mdc

Defines the core verification workflow: after any implementation step, always call codeloop_verify. If verification fails, callcodeloop_diagnose and fix the issues before moving on.

loop.mdc

Manages the verify-diagnose-fix loop. Tells the agent to continue iterating until the gate check passes with sufficient confidence.

recommendations.mdc

Guides the agent to use codeloop_release_readiness before marking work as complete, ensuring quality gates are met.

Expected Result

After setup you should see 29 CodeLoop tools registered in Cursor's MCP panel. They cluster into seven categories — the full tool reference has every parameter; here are the ones you will see fire most often:

See /docs/tools for the full parameter reference for every tool.

Verify it's actually triggering

After the activation chain, do a 30-second smoke test so you know the loop is live before you start coding:

1. Open a new chat in Cursor (existing chats use stale rules).
2. Type: “Add a one-line README. Then run codeloop_verify and show me the result.”
3. You should see the agent edit the file, then call codeloop_verify, then return structured JSON with passed, failed, and a path to artifacts/runs/<run_id>/meta.json.
4. From now on, the agent will call verify on its own — you will not need to ask.

If anything in the chain is missing, run npx codeloop doctor. It checks the API key, the MCP registration (project + global), the User Rule presence, the rule files in .cursor/rules/, and Node version, and prints a fix command for whatever is broken.

Troubleshooting

The agent never calls codeloop_verify on its own

This is almost always one of three things, in this order:

• The User Rule isn't pasted.Cursor Settings → Rules, Skills, Subagents → User Rules— the field should contain the rule from the “copy this exactly” section above. The MCP server can be installed and the rule still missing; that's the dormant state.
• You're in an old chat. Cursor caches rules per chat; open a brand-new chat to pick up changes.
• The MCP server is stale. Cursor Settings → Tools & MCPs → click the restart icon next to codeloop. Or fully quit and reopen Cursor.

Terminal commands keep showing a Skip/Run prompt

• Cursor Settings → Features > Terminal → Auto-Run Mode → Yolo (everything auto-runs) or Auto-Run with Allowlist (allowlist npm, npx, node, flutter, dotnet, git).
• This is a Cursor IDE setting; CodeLoop cannot bypass the approval UI. .cursor/rules/permissions.mdc documents which commands the loop needs.

CodeLoop tools don't appear in Cursor's MCP panel

• Verify the config: cat ~/.cursor/mcp.json (global) or cat .cursor/mcp.json(project) — both should be valid JSON with a codeloop entry.
• Check that CODELOOP_API_KEY is set: echo $CODELOOP_API_KEY (it must start with cl_live_).
• Restart Cursor after creating or editing the config file.
• Open Cursor Settings → Tools & MCPs and look for a red error on the codeloop row.

MCP server won't start

• Ensure Node.js 18+ is installed: node --version.
• Try running it directly: npx -y codeloop-mcp-server. The MCP server speaks stdio (not a TCP port) so port conflicts are not a thing — look at the stderr output for the real cause.
• On corporate networks, ensure npx can reach the npm registry; if not, set npm config set registry <your-mirror> and retry.

API key validation fails

• Confirm the key with echo $CODELOOP_API_KEY.
• Check if your trial has expired at the dashboard.
• Ensure you have internet connectivity — the first validation requires network; subsequent runs are cached for 24h.

Next Steps

• Cursor extension — zero-friction always-on activation
• Tool Reference — all 29 MCP tools, with parameters
• CLI reference — the same surface from the terminal
• Core concepts — the verify / diagnose / gate-check loop
• Configuration — customise CodeLoop for your project
• Troubleshooting — if something is not working, start here