> 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/guide/add-context-to-generate-better-code.md). # Add context to generate better code This guide walks you through setting up Sonar Vortex's [context augmentation](/agent-centric-development-cycle/guide/sonar-vortex-context-augmentation.md) features for your AI agent. For supported agents, the recommended setup paths are the SonarQube agent plugin and the SonarQube CLI. Both install an agent skill that can access context augmentation without exposing the tools through MCP. If you need direct MCP configuration or use a workflow not covered by these options, manually configure a locally running SonarQube MCP Server that connects to SonarQube Cloud. Using these features requires a SonarQube Cloud Team (annual) or Enterprise plan, plus a separate subscription to the Sonar Agent Essentials product. Three setup paths are available: * [SonarQube agent plugin](#install-with-the-sonarqube-agent-plugin): For Claude Code, Codex CLI, GitHub Copilot, Cursor, and Antigravity. The plugin installs and runs the integration for you. * [SonarQube CLI](#install-with-sonarqube-cli): To configure directly from your terminal without the plugin, or to automate installations with scripts. The `sonar integrate` command injects your project's current and intended architecture into the agent context, with no manual MCP configuration. * [SonarQube MCP Server](#install-with-the-sonarqube-mcp-server): For agents without a SonarQube plugin or CLI integration, or if you prefer direct MCP configuration. ## General prerequisites Before you start, make sure you meet the following prerequisites. #### SonarQube Cloud admin settings Context augmentation is enabled in your SonarQube Cloud organization's admin settings. #### Project settings Make sure your project is: * Connected to SonarQube Cloud. * Analyzed in your CI pipeline on a [long-lived branch](https://docs.sonarsource.com/sonarqube-cloud/analyzing-source-code/branch-analysis/main-vs-long-lived-branches). * Using SonarQube Cloud [Architecture](/sonarqube-cloud/architecture.md). ## Install with the SonarQube agent plugin ### Prerequisites specific to this setup Make sure you have the agent you want to configure installed on your machine. ### Step 1: Install the SonarQube plugin Install the SonarQube plugin for your agent: * Claude Code: Run `claude plugin install sonarqube@claude-plugins-official`, then restart Claude Code or run `/reload-plugins`. See [Claude Code](/agent-centric-development-cycle/developer-tools/agent-plugins/claude-code.md) for details. * Codex CLI: Run `codex plugin marketplace add SonarSource/sonarqube-agent-plugins`, start a Codex session, run `/plugins`, and install the SonarQube plugin. See [Codex CLI](/agent-centric-development-cycle/developer-tools/agent-plugins/codex-cli.md) for details. * GitHub Copilot: Run `copilot plugin install sonarqube@awesome-copilot`. See [GitHub Copilot](/agent-centric-development-cycle/developer-tools/agent-plugins/github-copilot-cli.md) for details. * Cursor: In Cursor's chat, run `/add-plugin sonarqube`. See [Cursor](/agent-centric-development-cycle/developer-tools/agent-plugins/cursor.md) for details. * Antigravity: Run `agy plugin install https://github.com/SonarSource/sonarqube-agent-plugins`. See [Antigravity](/agent-centric-development-cycle/developer-tools/agent-plugins/antigravity.md) for details. ### Step 2: Run the integration skill For Claude Code, Codex CLI, GitHub Copilot, and Antigravity, run the guided integration skill from an agent session opened in your project folder: * Claude Code: `/sonarqube:sonar-integrate` * Codex CLI: `$sonar-integrate` * GitHub Copilot: `/sonar-integrate` * Antigravity: `/sonarqube:sonar-integrate` The skill installs or updates the SonarQube CLI, authenticates it, and runs `sonar integrate` to install the context augmentation skill and configure your agent for the current project. For Cursor, run `sonar auth login` then `sonar integrate cursor --project ` from your project folder instead. ### Step 3: Restart your agent Restart your agent so the integration is loaded for the current project. ### Step 4: Verify your setup For Claude Code, Codex CLI, GitHub Copilot, and Antigravity, verify the setup using the same check as in the [SonarQube CLI setup](#install-with-sonarqube-cli): ask your agent *"What is the current architecture of the project? Limit the answer to the top-level blocks."* For Cursor, verify using the same architecture check: ask your agent *"What is the current architecture of the project? Limit the answer to the top-level blocks."* ## Install with SonarQube CLI Use this option to configure your agent directly from your terminal. This is useful when you don't have a plugin available or you're automating installations with scripts. For context augmentation, the SonarQube CLI installs the local context augmentation tool and an agent skill that uses it directly, without exposing the tools through MCP. The same command can also configure a [locally running SonarQube MCP Server](/sonarqube-mcp-server/setup/self-hosted.md#local-server-stdio) for SonarQube MCP tools other than the context augmentation tools. ### Prerequisites specific to this setup Make sure you have: * A supported agent installed on your machine. * [SonarQube CLI](https://docs.sonarsource.com/sonarqube-cli/) installed and authenticated. ### Step 1: Run the integration command From your project folder, run: ```bash sonar integrate --project ``` Replace `` with the supported integration you want to configure, for example `claude`, `copilot`, `codex`, `cursor`, or `antigravity`. This command configures the selected agent for the current project. It installs a project-specific context augmentation skill, binds it to the project key you provide, and configures the skill to access the context augmentation capabilities through the CLI. Context augmentation is project-specific rather than global. If you run `sonar integrate --global`, context augmentation is skipped; rerun the command without `--global` from a project directory to install it there. ### Step 2: Restart your agent Restart your agent so the generated skill and configuration are loaded for the current project. ### Step 3: Verify your setup Ask your agent "What is the current architecture of the projects? Limit the answer to the top-level blocks." The agent uses context augmentation to retrieve the current architecture (it might ask for your confirmation), then presents a high-level overview of the current project. Example response: ``` The architecture has 19 top-level modules with 35 dependencies between them: --- Foundation (no dependencies) ┌──────────────────┬──────────────────────┐ │ Module │ Depended on by │ ├──────────────────┼──────────────────────┤ │ proj-api-base │ All 18 other modules │ └──────────────────┴──────────────────────┘ --- Core layer (depend only on api-base) ┌────────────────────────────────────────────────┬────────────────────────────────────────┐ │ Module │ Purpose │ ├────────────────────────────────────────────────┼────────────────────────────────────────┤ │ proj-api-injection │ DI configuration interfaces │ │ proj-common │ Shared utilities │ │ proj-documentation │ Documentation │ │ proj-impl-configuration-gestalt │ Gestalt config implementation │ │ proj-peripheralcommadapter-loopback │ Peripheral loopback driver │ │ proj-plantoverview-base │ Base UI components │ │ proj-plantoverview-panel-loadgenerator │ Load generator panel │ │ proj-plantoverview-panel-resourceallocation │ Resource allocation panel │ │ proj-plantoverview-themes-default │ Default UI themes │ │ proj-strategies-default │ Default routing/dispatching strategies │ └────────────────────────────────────────────────┴────────────────────────────────────────┘ --- Mid layer (depend on api-base + common) ┌────────────────────────────────────────┬────────────────────────────┐ │ Module │ Also depends on │ ├────────────────────────────────────────┼────────────────────────────┤ │ proj-commadapter-loopback │ common │ │ proj-kernel-extension-http-services │ common │ │ proj-kernel-extension-rmi-services │ common │ │ proj-plantoverview-common │ common, plantoverview-base │ └────────────────────────────────────────┴────────────────────────────┘ --- Application layer (leaf modules, nothing depends on them) ┌─────────────────────────────┬────────────────────────────────────────────────────────────┐ │ Module │ Depends on │ ├─────────────────────────────┼────────────────────────────────────────────────────────────┤ │ proj-kernel │ api-base, common, commadapter-loopback │ │ proj-kernelcontrolcenter │ api-base, common, commadapter-loopback │ │ proj-modeleditor │ api-base, common, plantoverview-base, plantoverview-common │ │ proj-operationsdesk │ api-base, common, plantoverview-base, plantoverview-common │ └─────────────────────────────┴────────────────────────────────────────────────────────────┘ --- Dependency flow (simplified) proj-api-base └── proj-common └── proj-commadapter-loopback │ ├── proj-kernel │ └── proj-kernelcontrolcenter └── proj-plantoverview-base └── proj-plantoverview-common ├── proj-modeleditor └── proj-operationsdesk proj-api-base is the clear foundation — every module depends on it and nothing depends on the four application-layer modules (kernel, kernelcontrolcenter, modeleditor, operationsdesk). ``` ## Install with the SonarQube MCP Server Use this option to configure the SonarQube MCP Server manually. This is the setup path if you prefer direct MCP configuration, or if you're using an agent without a SonarQube plugin or CLI integration. > **Warning:** Context augmentation requires a [locally running SonarQube MCP Server](/sonarqube-mcp-server/setup/self-hosted.md#local-server-stdio) with a local filesystem mount. You can't use a SonarQube-hosted MCP server, whether [SonarQube Cloud-hosted](/sonarqube-mcp-server/setup/sonarqube-cloud-hosted.md#tool-availability-with-sonarqube-cloud) or [SonarQube Server-hosted](/sonarqube-mcp-server/setup/sonarqube-server-hosted.md), for CAG tools. ### Step 1: Export the SonarQube token environment variable Export the `SONARQUBE_TOKEN` [environment variable](/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 project-specific MCP configuration file > **Important:** Context augmentation requires a project-specific configuration. Don't use your global MCP configuration. The `SONARQUBE_TOOLSETS` value determines which [MCP toolsets](/sonarqube-mcp-server/reference/tools.md) are enabled. The following configuration enables the `cag` toolset required for context augmentation. ```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": "cag" } } } } ``` > **Note:** 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": ""` to the env object. > * Enable agentic analysis: To also enable agentic analysis, change `SONARQUBE_TOOLSETS` to `"cag,projects,analysis"`. > * 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: To mount the project workspace in read-only mode, specify `ro` instead of `rw`. Some tools might work in degraded mode. ### Step 3: Optimize tool invocation (recommended) Tool usage can be inconsistent depending on available tools, context, and agent behavior. To increase the chance of context augmentation tools being called at the right time, we recommend two additional configurations: #### 1. Ensure tools are loaded on startup Context augmentation tools are designed to be called automatically based on their descriptions, so they must be available to the model from the start. Some agents lazy-load MCP tool descriptions, meaning they are only made available when explicitly requested, which reduces the chance tools are invoked at the right time. Other agents load them eagerly by default, such as Codex, where [`defer_loading`](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#defer-loading-tools-in-an-mcp-server) defaults to `false`. If your agent lazy-loads tools, configure it to load them eagerly on startup. For example, with Claude Code, set [`ENABLE_TOOL_SEARCH`](https://code.claude.com/docs/en/mcp#configure-tool-search) to `false`. #### 2. Add an operational directive Adding a directive is optional. It is only needed if you want to enforce a specific Guide-phase workflow. Without one, context augmentation still works, and the agent decides the right workflow and when to call the tools on its own, based on the tool descriptions. To enforce a workflow, add the directive to your agent's system prompt or instructions file. Example directive: > **Note:** The following directive is one example of a [Guide-and-Verify](/agent-centric-development-cycle/guide/sonar-vortex-context-augmentation.md#guide-and-verify-loop) flow. Customize your guidance by picking from the available context augmentation tools to match your team's workflow. If you're only using context augmentation without [agentic analysis](/agent-centric-development-cycle/verify/sonar-vortex-agentic-analysis.md), you can remove the `VERIFY Phase` section. ``` # 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 AI agent to apply the new MCP configuration. ### Step 5: Verify your setup 1. Ask your agent "What is Guide and Verify?" Your agent describes 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 "What is the current architecture of the projects? Limit the answer to the top-level blocks." The agent calls the `get_current_architecture` tool (it might ask for your confirmation). The agent then presents a high-level overview of the current project. Example response: ``` The architecture has 19 top-level modules with 35 dependencies between them: --- Foundation (no dependencies) ┌──────────────────┬──────────────────────┐ │ Module │ Depended on by │ ├──────────────────┼──────────────────────┤ │ proj-api-base │ All 18 other modules │ └──────────────────┴──────────────────────┘ --- Core layer (depend only on api-base) ┌────────────────────────────────────────────────┬────────────────────────────────────────┐ │ Module │ Purpose │ ├────────────────────────────────────────────────┼────────────────────────────────────────┤ │ proj-api-injection │ DI configuration interfaces │ │ proj-common │ Shared utilities │ │ proj-documentation │ Documentation │ │ proj-impl-configuration-gestalt │ Gestalt config implementation │ │ proj-peripheralcommadapter-loopback │ Peripheral loopback driver │ │ proj-plantoverview-base │ Base UI components │ │ proj-plantoverview-panel-loadgenerator │ Load generator panel │ │ proj-plantoverview-panel-resourceallocation │ Resource allocation panel │ │ proj-plantoverview-themes-default │ Default UI themes │ │ proj-strategies-default │ Default routing/dispatching strategies │ └────────────────────────────────────────────────┴────────────────────────────────────────┘ --- Mid layer (depend on api-base + common) ┌────────────────────────────────────────┬────────────────────────────┐ │ Module │ Also depends on │ ├────────────────────────────────────────┼────────────────────────────┤ │ proj-commadapter-loopback │ common │ │ proj-kernel-extension-http-services │ common │ │ proj-kernel-extension-rmi-services │ common │ │ proj-plantoverview-common │ common, plantoverview-base │ └────────────────────────────────────────┴────────────────────────────┘ --- Application layer (leaf modules, nothing depends on them) ┌─────────────────────────────┬────────────────────────────────────────────────────────────┐ │ Module │ Depends on │ ├─────────────────────────────┼────────────────────────────────────────────────────────────┤ │ proj-kernel │ api-base, common, commadapter-loopback │ │ proj-kernelcontrolcenter │ api-base, common, commadapter-loopback │ │ proj-modeleditor │ api-base, common, plantoverview-base, plantoverview-common │ │ proj-operationsdesk │ api-base, common, plantoverview-base, plantoverview-common │ └─────────────────────────────┴────────────────────────────────────────────────────────────┘ --- Dependency flow (simplified) proj-api-base └── proj-common └── proj-commadapter-loopback │ ├── proj-kernel │ └── proj-kernelcontrolcenter └── proj-plantoverview-base └── proj-plantoverview-common ├── proj-modeleditor └── proj-operationsdesk proj-api-base is the clear foundation — every module depends on it and nothing depends on the four application-layer modules (kernel, kernelcontrolcenter, modeleditor, operationsdesk). ``` ## Troubleshooting ### Enabling detailed logs If you encounter issues with the context augmentation MCP tools, first enable detailed logging to identify the root cause. Add the following environment variables to the `env` object in your MCP configuration: ```json "SONARQUBE_DEBUG_ENABLED": "true", "SONAR_LOG_LEVEL": "TRACE" ``` Then expose them to the Docker container by adding these entries to the `args` array: ```json "-e", "SONARQUBE_DEBUG_ENABLED", "-e", "SONAR_LOG_LEVEL" ``` ### Exporting logs After you enable detailed logging, use one of the following methods to retrieve the logs. #### Option 1: Export logs from the running Docker container 1. Identify the container ID used by the MCP server: ```bash docker ps ``` If multiple containers are running the same image, filter by your project key: ```bash docker ps -q | xargs docker inspect --format '{{.Id}} {{.Config.Env}}' | grep "SONARQUBE_PROJECT_KEY=" | awk '{print $1}' ``` Replace `` with the project key configured in your MCP server. 2. Extract the logs as an archive file: ```bash docker exec sh -c "cd /app/storage && tar czf - logs/" > logs.tar.gz ``` #### Option 2: Mount logs to a local directory Add the following volume mount to the `args` array in your MCP configuration, replacing `` with an absolute path to an existing local directory: ```json "-v", ":/app/storage/logs:rw" ``` After you restart the MCP server, logs are written directly to that local directory. ### Context augmentation tools not loading **Symptom:** After setting up the MCP server, only two tools appear: `search_my_sonarqube_projects` and `run_advanced_code_analysis` and none of the context augmentation tools are available. **Fix:** Pull the latest version of the Docker image, then restart your AI agent: ```bash docker pull sonarsource/sonarqube-mcp ``` *** ### SonarQube connection failed **Symptom:** After you complete the setup, architecture tools don't appear. Only `get_guidelines` and two general SonarQube MCP tools (`search_my_sonarqube_projects` and `run_advanced_code_analysis`) are available. The following error messages appear in the logs: ```log SonarQube connection failed: [Errno -2] Name does not resolve Architecture: SonarQube not available. Architecture loading skipped. Architecture tools will be unavailable. ``` **Fix:** Verify the value of `SONARQUBE_URL` in your MCP configuration. It must point to the SonarQube Cloud instance hosting your project's analysis. For example, `https://sonarcloud.io`. **Additional fix for Linux systems on corporate or restricted networks:** The default Docker DNS pass-through might be blocked, preventing the container from resolving hostnames. This issue can also appear intermittently. Pass an explicit DNS server address to Docker by adding the following entry to the `args` array: ```json "--dns=8.8.8.8" ``` Replace `8.8.8.8` with your organization's DNS server address if needed. As a last resort, configure the container to share the host network: ```json "--network=host" ``` Or instruct the container to use your host's DNS resolver directly: ```json "--dns=127.0.0.53" ``` > **Warning:** Using `--network=host` removes Docker's network isolation for this container, which might reduce security. Use this option only if other approaches haven't resolved the issue. ### Architecture tools fail with "Universal Dependency Graph (UDG) not loaded" **Symptom:** Architecture tools such as `get_type_hierarchy` and `search_by_signature_patterns` return an error message: "Universal Dependency Graph (UDG) not loaded". **Cause:** The MCP server is configured to use a branch that has not been analyzed or does not exist in SonarQube Cloud. **Fix:** Verify that the `SONAR_SQ_BRANCH` environment variable in your MCP configuration points to a valid branch that SonarQube Cloud has analyzed. If you recently created the branch or changed its name, make sure a fresh analysis has completed successfully. ## Need help? Post a question on the [community forum](https://community.sonarsource.com/) or contact support if your license includes access to [commercial support](https://www.sonarsource.com/support/). ## Related pages * [Context augmentation](/agent-centric-development-cycle/guide/sonar-vortex-context-augmentation.md) * [Agentic analysis](/agent-centric-development-cycle/verify/sonar-vortex-agentic-analysis.md) * [Claude Code plugin](/agent-centric-development-cycle/developer-tools/agent-plugins/claude-code.md) * [Codex CLI plugin](/agent-centric-development-cycle/developer-tools/agent-plugins/codex-cli.md) * [GitHub Copilot plugin](/agent-centric-development-cycle/developer-tools/agent-plugins/github-copilot-cli.md) * [Cursor plugin](/agent-centric-development-cycle/developer-tools/agent-plugins/cursor.md) * [Antigravity plugin](/agent-centric-development-cycle/developer-tools/agent-plugins/antigravity.md) * [MCP Server](https://docs.sonarsource.com/sonarqube-mcp-server/) * [Tools](/sonarqube-mcp-server/reference/tools.md) * [Architecture](/sonarqube-cloud/architecture.md) --- # 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/guide/add-context-to-generate-better-code.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.