Vortex with the MCP server

How to install Vortex by configuring the SonarQube MCP server into any agent

Vortex can be used through the SonarQube MCP server if the CLI does not offer a specific integration for your agent.

Prerequisites

• Vortex can only be used through MCP with the local (stdio) version of the SonarQube MCP server, because it needs access to local files to perform the analysis. The SonarQube-hosted MCP server, reached over HTTP, cannot be used for Vortex.
• The SonarQube MCP Server requires a Docker-compatible installation, for example Docker Desktop or Colima on macOS.

Step 1: Export the SonarQube token environment variable

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

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

Step 2: Add or edit your MCP configuration file

MCP settings files are located at the following paths:

• .cursor/mcp.json for Cursor IDE
• .mcp.json for Claude Code
• ~/.gemini/config/mcp_config.json for Antigravity
• .codex/config.toml for Codex

  • use a TOML config instead of JSON
• .vscode/mcp.json for Copilot in Visual Studio Code

Note: Replace the placeholders above with appropriate values. ⚠️ The path format is critical:

• Paths must be absolute. Relative paths like ./ or ../ are not accepted.
• On Windows, use forward slashes, for example C:/Users/john/projects/myapp. Don't use back slashes, for example C:\\Users\\john\\projects\\myapp.

The SONARQUBE_TOOLSETS value determines which MCP toolsets are enabled. The configuration below enables the analysis, cag and projects toolsets required for Sonar Vortex.

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

Note: Optional configurations:

• 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".
• Read-only volume mounting of the project workspace: The project workspace can be mounted in read-only mode by specifying ro instead of rw. Some tools may work in degraded mode.

Step 3: 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 Sonar Vortex tools appropriately.

Add the directive to your agent's system prompt or instructions file.

Example directive:

# SonarQube Agentic Workflow - Usage Directive (MUST FOLLOW)

**Always use the Guide-and-Verify workflow** for writing and modifying code.

## GUIDE Phase - Before Writing or Editing Code

**Before writing 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_type_hierarchy` - check inheritance

**Before adding or updating a third-party dependency** you MUST:
- Call `check_dependency` with the package URL (purl) to check for vulnerabilities, malware, and license compliance

## VERIFY Phase - After Writing or Editing 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:
   - `filePath`: The project-relative path to the file (e.g., `src/main/java/MyClass.java`)
   - `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., `java:S1874`)
   - **Mandatory Fixes:** You are prohibited from committing code with **CRITICAL** or **HIGH** issues. Implement fixes based on the rule's rationale and recommended guidance immediately.
4. **Verification:** After applying fixes, re-run the analysis to ensure issues are resolved and no regressions were introduced.

Step 4: Restart your agent

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

Step 5: Verify your setup

1. Ask your agent "What is Guide and Verify?" You should see a description of the SonarQube Agentic workflow as configured in step 3.

Example response

 "Guide & Verify" is a workflow defined in your project's CLAUDE.md file for writing and modifying code. It has two phases:
                                                                                                                                                                                                                                                 
  GUIDE Phase (before writing code):                                                                                                                                                                                                             
  - Fetch project guidelines and coding standards via get_guidelines                                                                                                                                                                             
  - Locate existing code using search tools                                                                                                                                                                                                      
  - Read the relevant implementation via get_source_code                                                                                                                                                                                       
  - For architectural changes: check current/intended architecture, trace call flows, find usages, inspect type hierarchies

  VERIFY Phase (after writing code):
  1. Read — reload all modified source files
  2. Analyze — run run_advanced_code_analysis on each changed file against the active branch
  3. Evaluate & Fix — look up flagged rules with show_rule, and mandatory fix any CRITICAL or HIGH severity issues before committing
  4. Re-verify — re-run analysis to confirm fixes and check for regressions

  In short, it's a SonarQube-backed quality gate that requires you to understand existing code before touching it and validate every change with static analysis before considering it done.

1. Ask your agent "Verify the file path/to/file.java." You should see it invoke the run_advanced_analysis tool (it might ask for confirmation). You should see a report of which issues are currently present in the file, broken down by severity.

Example response

Here is a summary of the 21 issues found:                                                                                                                                                                                                      
                                                                                                                                                                                                                                                 
  ---                                                                                                                                                                                                                                            
  Analysis Results                                                                                                                                                                                                                               
                                                                                                                                                                                                                                                 
  CRITICAL / HIGH — None
                                                                                                                                                                                                                                                 
  No blocking issues were found. The file is safe to commit as-is from a severity standpoint.                                                                                                                                                    
                                                                                                                                                                                                                                                 
  ---                                                                                                                                                                                                                                            
  Medium Issues                                                                                                                                                                                                                                  

  java:S107 — Too many constructor parameters (line 137)
  The private OrderSequence(...) constructor has 14 parameters, exceeding the limit of 7. This is a common pattern for immutable value objects using the "wither" pattern, but SonarQube flags it nonetheless. Refactoring would require
  introducing a builder, which is a non-trivial API change.

  java:S3358 — Nested ternary (line 720)
  ref == null ? List.of("") : List.of(ref.getName())
  Inside an already-ternary expression. Should be extracted into a variable or helper method.

  ---
  Low / Info Issues

  java:S1133 — Deprecated code not yet removed (lines 66, 256, 269)
  The type field and the getType() / withType() methods are annotated @Deprecated with a scheduled removal at 8.0. SonarQube reminds you to eventually remove them.

  java:S1123 — Missing @deprecated Javadoc tag (line 66)
  The type field is annotated with @Deprecated but its Javadoc comment does not include a @deprecated tag explaining the migration path.

  java:S1874 — Use of deprecated type field (lines 124, 154, 173, 193, 213, 233, 351, 389, 449, 485, 523, 560, 600, 637, 673) — 15 occurrences
  Every internal usage of the deprecated type field triggers this rule. These will all be resolved once type is removed in 8.0.

  ---
  Summary

  ┌───────────────┬───────┬───────────────────────┐
  │   Severity    │ Count │        Action         │
  ├───────────────┼───────┼───────────────────────┤
  │ CRITICAL/HIGH │ 0     │ None required         │
  ├───────────────┼───────┼───────────────────────┤
  │ Medium        │ 2     │ Optional improvement  │
  ├───────────────┼───────┼───────────────────────┤
  │ Low/Info      │ 19    │ Track for 8.0 cleanup │
  └───────────────┴───────┴───────────────────────┘

  The file is clean from a blocking-issue perspective. The medium-severity nested ternary at line 720 is the only quick improvement worth considering now. Everything else is tracked for the 8.0 deprecation removal cycle.