Agentic Analysis

Agentic Analysis enables AI agents to verify generated code with the same precision as a full CI scan, but in seconds instead of minutes, closing the Guide-and-Verify loop.

This feature is in Beta stage and is only available with SonarQube Cloud projects. See the Product release lifecycle page for more information on release stages.

The Agentic Workflow

Agentic Analysis is the Verify phase of the SonarQube Agentic Workflow — a continuous loop that ensures AI-generated code is both architecturally sound and meets your quality standards.

1. Guide: Context Augmentation injects architectural awareness and coding guidelines into the LLM context before code generation.

2. Generate: The LLM generates code based on the augmented context.

3. Verify: Agentic Analysis verifies the generated code with full CI-level precision.

4. Loop: The LLM refines the code based on analysis results and repeats until quality gates pass.

This workflow unlocks AI productivity without trade-offs, ensuring clean pull requests pass quality gates the first time, leading to faster code reviews with no back-and-forth.

For the Guide phase, see Context Augmentation.

---

Overview

With Agentic Analysis, AI agents can analyze code changes with the same precision as a full CI scan, but in seconds instead of minutes. Agentic Analysis leverages context collected during the last SonarQube CI analysis and restores it on-demand for single-file or multi-file analysis.

Supported languages

Agentic Analysis is available for the following languages:

• Java

• Python

• Javascript/Typescript

• CSS

• HTML

• XML

Secrets detection and the IaC domains Docker, Kubernetes, and Terraform, are also supported.

If your Java project was analyzed using Automatic analysis, only basic analysis results are returned.

About the context mechanism

Agentic Analysis achieves high-precision analysis through a two-phase approach: it first collects context during CI analysis, then restores that context on demand.

Phase 1: Context collection

During a regular CI analysis, SonarQube may collect and store:

• Dependencies: JAR files, npm packages, or Python libraries the project uses.

• Compiled artifacts: .class files.

• Type information: Symbol tables, type hierarchies, import graphs.

• Build configuration: Project structure, source paths, compiler settings.

This context is stored in the SonarQube Cloud backend (AWS), tagged by project key and branch.

Phase 2: Context restoration

When analyzing files using Agentic Analysis, the context collected for this project during a CI analysis is restored, based on the specified project and branch name. This allows running an analysis with full access to dependencies and compiled artifacts. Analysis results have a level of precision that matches a full CI scan analysis.

---

SonarQube MCP Server Integration

Prerequisites

Your project must be:

• Connected to SonarQube Cloud.

• Analyzed in your CI pipeline on a long-lived branch.

• Analyzed in SonarQube Cloud after the Agentic Analysis service was enabled for the organization to ensure context collection.

Agentic Analysis is compatible with Claude Code, Cursor, Codex, Gemini CLI, and VS Code with Copilot.

Integration steps

Step 1: Install the SonarQube MCP Server

First, install the SonarQube MCP Server in your MCP client using the SonarQube Cloud setup. Detailed setup instructions are available for the most popular MCP clients; find yours in the IDE setup article.

Step 2: Export the SonarQube Token environment variable

Export the SONARQUBE_TOKEN environment variable with a valid Personal Access Token (PAT) for your project.

# macOS/Linux (Bash/Zsh)
export SONARQUBE_TOKEN="{<YourUserToken>}"

Step 3: Set the Agentic Analysis environment variable

Set your SONARQUBE_ADVANCED_ANALYSIS_ENABLED environment variable to true (default is false). This makes the run_advanced_code_analysis tool available in the SonarQube MCP Server.

For more information on the tool, see the SonarQube MCP Tools section.

Step 4: Add or edit your project-specific MCP configuration file

Agentic Analysis requires a project-specific configuration. Do not use your global MCP configuration.

Project-specific MCP settings files are located in the following files (relative to project root):

• .cursor/mcp.json for Cursor IDE

• .mcp.json for Claude Code

• .gemini/settings.json for Gemini CLI

• .codex/config.toml for Codex

  • use a TOML config instead of JSON

• .vscode/mcp.json for Copilot in Visual Studio Code

Replace the placeholders above with appropriate values:

• Paths must be absolute: Relative paths like ./ or ../ are not accepted.

  • ⚠️ The path format is critical.

• Windows users:

  • Use forward slashes. Example: C:/Users/john/projects/myapp

  • Do not use back slashes. Example: C:\Users\john\projects\myapp

{
  "mcpServers": {
    "sonarqube-agentic-analysis": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--pull=always",
        "-e", "SONARQUBE_URL",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_ORG",
        "-e", "SONARQUBE_PROJECT_KEY",
        "-e", "SONARQUBE_TOOLSETS",
        "-e", "SONARQUBE_ADVANCED_ANALYSIS_ENABLED",
        "-v", "/ABSOLUTE/PATH/TO/YOUR/PROJECT:/app/mcp-workspace:rw",
        "mcp/sonarqube"
      ],
      "env": {
        "SONARQUBE_URL": "https://sonarcloud.io",
        "SONARQUBE_ORG": "<YourOrganizationKey>",
        "SONARQUBE_PROJECT_KEY": "<YourProjectKey>",
        "SONARQUBE_TOOLSETS": "cag,projects,analysis",
        "SONARQUBE_ADVANCED_ANALYSIS_ENABLED": "true"
      }
    }
  }
}

Optional configurations:

• SONAR_SQ_BRANCH: Provide it when not using git, or when your git branch name doesn't match the branch name in SonarQube. Add "-e", "SONAR_SQ_BRANCH", to the args array and "SONAR_SQ_BRANCH": "<YourBranchName>" to the env object.

• Agentic Analysis tools only: By default, SONARQUBE_TOOLSETS enables both Agentic Analysis and Context Augmentation tools (cag,projects,analysis). If you want to use Agentic Analysis without Context Augmentation, change the value to "analysis,projects".

• Include default SonarQube MCP tools: To include the default SonarQube MCP tools in addition to the Agentic Workflow tools, change the SONARQUBE_TOOLSETS value to: "analysis,issues,projects,quality-gates,rules,duplications,measures,security-hotspots,dependency-risks,coverage,cag"

Step 5: Configure agent operational constraints (Recommended)

Tool usage can be inconsistent depending on available tools, context, and agent behavior. To ensure the agent follows the Guide-and-Verify workflow consistently, explicitly guide your AI agent to use the Agentic Analysis tools appropriately.

How to configure:

• Cursor: Create a .cursor/rules/sonar-agentic-analysis.md Cursor rule file

• Claude Code: Add the directive to your CLAUDE.md in the project root, or use Claude Skills

• Codex: Add the directive to your AGENTS.md file in the project root

• Gemini CLI: Add the directive to your GEMINI.md file in the project root

• Copilot: Add the directive to your CLAUDE.md in the project root

Example directive:

The example below covers the full Guide-and-Verify workflow. If you are only using Agentic Analysis without Context Augmentation, you can remove the GUIDE Phase section.

# SonarQube Agentic Workflow - Usage Directive (MUST FOLLOW)

**Always use the Guide-and-Verify workflow** for code generation and modification.

## GUIDE Phase - Before Generating Code

**Before generating or editing code** you MUST:
1. Call `get_guidelines` for project context and coding standards
2. Locate existing code with `search_by_signature_patterns` or `search_by_body_patterns`
3. Read implementation with `get_source_code`

**When changing architecture or dependencies** you MUST:
- Check `get_current_architecture` and `get_intended_architecture`
- Analyze impact using:
  - `get_upstream_call_flow` / `get_downstream_call_flow` - trace method calls
  - `get_references` - find all usages
  - `get_classlike_structure_hierarchy` - check inheritance

## VERIFY Phase - After Generating Code

You must strictly follow this Analyze-Then-Commit workflow for every code modification. No code is considered complete until it has passed the following SonarQube validation loop:

1. Read Phase: After any modification or before commit, use the `Read` tool to load the current state of all relevant source files.
2. Analysis Phase: For every new or modified file, you must call `run_advanced_code_analysis` using:
   * `projectKey`: <YourProjectKey>
   * `filePath`: The project-relative path to the file.
   * `fileContent`: The full, updated content of the file.
   * `branchName`: The active development branch.
   * `fileScope`: "MAIN" or "TEST" depending on the code type.
3. Evaluation & Remediation:
   * Rule Lookup: For every issue flagged, call `show_rule` with the specific rule key (e.g., `python:S1192`).
   * Mandatory Fixes: You are prohibited from committing code with **CRITICAL** or **HIGH** issues. You must implement fixes based on the rule's rationale and recommended guidance immediately.
4. Verification: After applying fixes, you must re-run the analysis to ensure the issues are resolved and no regressions were introduced.

Step 6: Restart your agent

Restart your agent and make sure that your MCP configuration is taken into account and applied correctly.

---

Direct API calls

Depending on the way you have set up your AI agent to work, you may want to run an Agentic Analysis without integrating with the SonarQube MCP Server. In this case, you can make an API call to the Agentic Analysis API directly.

Prerequisites

The project must have been analyzed in SonarQube Cloud after the Agentic Analysis service was enabled for the organization to ensure context collection.

Calling the Agentic Analysis API

To trigger an Agentic Analysis through an API call, send a POST request to https://api.sonarcloud.io/a3s-analysis/analyses.

Provide the following parameters in your request:

Parameters

projectKey (key, required) The key of your project (go to your project > Information to find it). branchName (string, required) Branch name used to retrieve the latest analysis context. filePath (string, required) Project-relative path of the file to analyze (e.g., "src/main/java/MyClass.java"). fileContent (string, required) The original content of the file to analyze. fileScope (string, optional) Defines in which scope the file originates from (main or test code): "MAIN" or "TEST". Default is "MAIN".

Example with curl

Here is an example of an API call using curl:

curl -X 'POST' \
  'https://api.sonarcloud.io/a3s-analysis/analyses' \
  -u '<YourSonarQubeCloudPersonalAccessToken>:' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "organizationKey": "<YourOrganizationKey>",
    "projectKey": "<YourProjectKey>",
    "branchName": "main",
    "filePath": "<FilePath>",
    "fileContent": "<FileContent>",
    "fileScope": "MAIN"
  }'

---

Related pages

• Context Augmentation

• SonarQube MCP Server

• SonarQube MCP Server Tools