Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Developer

Cursor

Install secrets-detection hooks, the SonarQube MCP Server, and Vortex analysis and Vortex context features for Cursor with the SonarQube CLI.

sonar integrate cursor configures the SonarQube CLI to work alongside Cursor. In an interactive terminal, the command shows these recommended components, then asks you to install them or customize the selection (see Install confirmation):

  • Secrets detection: a beforeSubmitPrompt hook that scans prompts before they're sent to the model, plus two file-read hooks (beforeReadFile and preToolUse) that scan files before Cursor reads them. Together they block any operation that would expose a secret.

  • The SonarQube MCP Server, which lets Cursor fetch projects, issues, and rules directly.

  • Vortex (when your connection has a Vortex subscription: SonarQube Cloud Team (annual) or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions): installs Vortex analysis and Vortex context together. It adds:

    • Vortex analysis instructions as an always-applied rule in ~/.cursor/rules/ that tells Cursor to run sonar analyze agentic on your changes at the end of a turn

    • A sessionStart hook that injects Vortex context when a session starts, letting Cursor use project guidelines, architecture, semantic navigation, and dependency context

Pass --non-interactive to accept every offered component without prompts (see Non-interactive install).

Prerequisites

Install

Install once for this machine:

sonar integrate cursor

The command writes hooks and config to ~/.cursor/ and applies to desktop Cursor sessions on this machine. See Project versus global scope.

Warning: Cursor's cloud and background agents only pick up project-level hooks, not global ones. Desktop Cursor sessions still run the installed hooks.

Note: If a previous install wrote .agents/skills/sonar-context-augmentation/SKILL.md, update to SonarQube CLI 1.8.0 or newer, then re-run sonar integrate cursor to replace that leftover skill with the session-start hook.

What the command does

The integrator runs in two phases:

  1. Validation. It checks that your saved token can reach SonarQube. On SonarQube Cloud, your connection must include an organization. An invalid token stops setup and tells you to run sonar auth login. An unreachable server stops setup and asks you to check the server URL and your network connection.

  2. Installation. The CLI shows a What will be installed summary of the recommended components (secrets detection, MCP server, and Vortex when eligible). In an interactive terminal, choose Install recommended to write that set, or Customize to accept or decline each component and then press Enter. Components that are not available are skipped with an explanation. In non-interactive mode, every eligible component is installed without prompts. The CLI then writes the accepted components into ~/.cursor/.

    Common skip reasons include:

    • Your connection does not have a Vortex subscription (only available with SonarQube Cloud Team (annual) or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions).

Secrets hooks

Cursor receives three secrets detection hooks in ~/.cursor/hooks.json:

Hook event
Matcher
What it scans

beforeSubmitPrompt

UserPromptSubmit

The prompt you send to Cursor

beforeReadFile

Read|TabRead

Files before Cursor reads them from disk

preToolUse

Read

Files when the agent issues a Read tool call

The two file-read hooks work together as defense in depth. beforeReadFile intercepts disk reads, but files already open in the editor can bypass it. preToolUse covers agent Read tool calls at a different layer. When either hook detects a secret, Cursor blocks the read and the CLI appends the file to .cursorignore, which blocks subsequent reads natively.

If you're not authenticated or the sonar-secrets binary is missing, all three hooks fail closed and block the operation with a remediation message instead of silently allowing it through. See When scanning is inactive.

Options

Option
Description

--non-interactive

Non-interactive mode (no prompts).

--global, -g

Deprecated since 1.9.0. The install is already global; using the flag prints a warning and does not change the installation scope.

Where files are installed

Location
Hook and config location

User home

~/.cursor/ (hooks, rules, MCP config)

Shared binaries

~/.sonar/sonarqube-cli/bin/

State for installed integrations is recorded in ~/.sonar/sonarqube-cli/state.json. See State and storage.

Restart Cursor

Cursor reads its hook and MCP configuration at startup. Restart Cursor for the integration to take effect.

Vortex analysis and Vortex context

When you run sonar integrate cursor against a SonarQube Cloud project, the command writes an always-applied rule in ~/.cursor/rules/sonar-agentic-analysis.mdc that tells Cursor to run sonar analyze agentic --depth DEEP on every file it modified that turn in a single command (repeat --file for each path, or fall back to the git change set). The rule omits --project because each file is analyzed against the project that owns it. In a repository with several projects, the rule tells Cursor to run that command from a directory that contains every file changed in the turn, usually the repository root. Re-run sonar integrate cursor so an existing rule picks up that paragraph. If analysis reports that no project is configured, the rule tells the agent to stay silent for the rest of the session instead of repeating a skip notice. See Files and the project root. Cursor's hook model does not support injecting analysis findings back into the conversation the way Claude Code and Codex hooks do. The CLI uses the same instructions-based pattern as GitHub Copilot CLI.

It also writes a sessionStart hook in ~/.cursor/hooks.json that injects Vortex context when a Cursor session starts. When context cannot load, Cursor asks the agent to tell you once per session. See When Vortex context does not load. If a previous install wrote .agents/skills/sonar-context-augmentation/SKILL.md, update to SonarQube CLI 1.8.0 or newer, then re-run sonar integrate cursor to replace that leftover skill with the session-start hook.

For overviews of these features, see Vortex analysis and Vortex context.

Verify it works

Test the secrets hook

  1. Create a file in your project with a fake-looking but secret-shaped value:

  2. Ask Cursor to read it: "Read secrets.js."

  3. Cursor should block the read and explain that the file contains a secret. The CLI also adds the file to .cursorignore.

After you've confirmed the hook is active, delete the test file.

Also run sonar system status to confirm the Cursor integration reports Secrets Hook: CONFIGURED. If the hook entry exists but the backing script is missing or malformed, status shows CONFIGURED / INVALID CONFIG and recommends re-running sonar integrate cursor. See Check system status.

Test the MCP server

In Cursor, ask: "Use the SonarQube MCP Server to list my open projects." Cursor should call SonarQube and return your project list. If it does not, run sonar auth status to confirm the underlying token is healthy and restart Cursor. If the connection closes with an error, see MCP server connection closes.

MCP server connection closes

If Cursor logs MCP error -32000: Connection closed and the SonarQube MCP Server does not start, your organization's Cursor Enterprise MCP controls may run the server in a sandbox that blocks access to the container runtime. The SonarQube CLI configures Cursor to start the server with sonar run mcp, and that command starts the MCP server in a local container, which means it cannot start when the sandbox blocks the runtime. Any container-based MCP server fails the same way. Other causes of this error exist, for example a container runtime that is not running.

To fix this, use one of these options:

  • Ask a Cursor team administrator to add a Command entry that matches sonar run mcp in Team Settings > MCP Configuration, with the network mode set to No sandbox. Cursor matches Command entries against the full command, including its arguments, and supports * wildcards.

  • Connect Cursor to a SonarQube-hosted MCP server instead. Hosted servers do not run a container on your machine. They expose fewer tools and do not include the Sonar Vortex analysis and context tools.

Test Vortex analysis

In Cursor, make a code change and end the turn. Cursor should run Vortex analysis on your changes per the installed rule. This requires a Sonar Vortex subscription.

Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

In non-interactive mode the CLI does not prompt for feature selection, install confirmation, token repair, or feature removal; it installs every component that is not explicitly skipped. When you authenticate with environment variables, integrate commands also run in non-interactive mode even without the flag. Run sonar auth status afterward to confirm everything is configured correctly.

Uninstall

Run sonar integrate cursor again in an interactive terminal and choose Customize. For each installed feature, the CLI asks Keep?: answer No, confirm Proceed with removal?, and the CLI removes hooks, rules, and state for that feature. Vortex is removed as one unit (Vortex analysis rule and session-start hook). See integrations/README.md for the full flow.

For a manual cleanup or non-interactive environments:

  1. Delete the SonarQube hook files and rules written under ~/.cursor/.

  2. Remove the SonarQube MCP Server entry from your Cursor configuration.

  3. Remove the integration entry from ~/.sonar/sonarqube-cli/state.json (under integrations.installed).

See Uninstalling for the full removal procedure.

Last updated

Was this helpful?