> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/how-to-guides/install-vortex-with-mcp.md). # Vortex with the MCP server 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` [Environment variables](/sonarqube-mcp-server/reference/environment-variables.md#common-variables) with a valid [Personal Access Token (PAT)](/sonarqube-cloud/managing-your-account/managing-tokens.md) for your project. ```bash # macOS/Linux (Bash/Zsh) export SONARQUBE_TOKEN="{}" ``` ## 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](/sonarqube-mcp-server/reference/tools.md) are enabled. The configuration below enables the `analysis`, `cag` and `projects` toolsets required for Sonar Vortex. ```json { "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": "", "SONARQUBE_PROJECT_KEY": "", "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. ``` 2. 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. ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/how-to-guides/install-vortex-with-mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.