> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# SonarQube
> Read and act on SonarQube / SonarQube Cloud code-quality data from Agent Factory agents and Builder workflows
The SonarQube app exposes the [SonarQube](https://www.sonarsource.com/products/sonarqube/) and [SonarQube Cloud](https://sonarcloud.io) Web API. It can be consumed two ways: as a remote MCP server that **Agent Factory** agents call as tools, or as a Builder app whose instructions you call directly from DSUL. It covers projects, components, issues, security hotspots, measures, metrics, quality gates, quality profiles, rules, organizations, user tokens, analyses, branches, webhooks and SVG badges. Authentication is a **SonarQube User Token** stored in the workspace and resolved server-side — never passed through the agent.
Issues, security hotspots, rules and quality profiles to triage code findings.
Measures, metric definitions, history, quality-gate status and analyses.
Projects, organizations, branches, webhooks, user tokens and SVG badges.
## Who is this for?
This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.
You build agents in **Agent Factory** and want them to use SonarQube. → *Agent builder* tab.
You run the platform and set up SonarQube once for everyone. → *Platform admin setup* accordion below.
You write Builder automations (DSUL) that call SonarQube operations directly. → *Workspace builder* tab.
## Prerequisites
* A **SonarQube** server (self-hosted) or a **SonarQube Cloud** account.
* A **User Token** generated in **My Account > Security > Generate Tokens** (passed server-side as `Authorization: Bearer `).
* The **API base URL** of your instance:
* SonarCloud: `https://sonarcloud.io/api`
* Self-hosted: `https:///api`
* For SonarCloud only: the **organization key** that owns your projects (most search and create operations require it — use `searchOrganizations` to discover the keys visible to your token).
**Goal:** SonarQube is a **per-workspace** connector — each workspace pastes its own SonarQube User Token (see the *Workspace builder* tab), so there is **no platform-wide credential to provision**. The only optional platform task is to publish SonarQube as a reusable **capability** in AI Governance so agent builders can enable it from the catalog instead of pasting a raw MCP endpoint.
There is no shared SonarQube credential and no central OAuth client for this connector. The SonarQube User Token always lives in the consuming workspace and is resolved server-side. A Governance capability you publish here points at a specific workspace's MCP endpoint; that workspace still owns the credential.
## Declare the capability in AI Governance (optional)
Create (or edit) the **SonarQube** capability.
Set the capability's MCP server URL to the connector's **MCP Endpoint** (the workspace running the connector), and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` in the scope is what lets the connector identify the calling agent.
Once created, the capability appears in the capability picker for agent builders in your organization, who enable it on their agents. Access to the catalog follows your organization's existing roles; there is no per-capability role grant for this connector.
Declaring the capability makes the connector **available**; the SonarQube credential is still owned by the workspace that installed the app. There is **no OAuth auth-config JSON** to attach in Governance: authentication is a server-side User Token, not a per-user OAuth flow.
***
## Agent builder
**Goal:** let an agent you build in Agent Factory read and act on SonarQube code-quality data through MCP tools.
Before an agent can call the connector, a *Workspace builder* must have installed and configured the SonarQube app in a workspace (see the *Workspace builder* tab). Optionally, a *Platform admin* may have published a SonarQube capability in AI Governance (see the *Platform admin setup* accordion above).
The SonarQube credential is resolved server-side from the installed app's configuration — never exposed to the agent. Your agent is identified through the capability *Scope* that Agent Factory injects.
Follow the *Workspace builder* tab: install **SonarQube** in your workspace and provide the **API base URL** and **User Token**.
In your agent, add a capability pointing at the workspace's **MCP Endpoint** URL, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The server URL and identity propagation are then wired; the SonarQube token is fetched server-side from the app configuration.
Wiring the capability is not enough — the agent also needs to know the MCP exists and when to reach for it. Add a short paragraph to the agent's system prompt. Copy-pasteable starter:
```text theme={null}
You have access to the SonarQube MCP server. Use it whenever the user asks about code-quality data — projects, issues, security hotspots, measures, quality gates, rules or badges. Examples: "List the blocker issues in project X", "What's the coverage of auth-service?", "Show the security hotspots opened this week", "Why is the quality gate failing on main?". On SonarCloud, most search and create operations need an organization key — call searchOrganizations first if you don't know it. Prefer calling MCP tools directly over guessing, and confirm with the user before any destructive action (mark issues as false positive, change severity, delete a project or branch).
```
Refine the trigger keywords (project keys, branch names, rule families) so the agent reliably picks up the right intent in your context.
**Legacy AI Knowledge agents** (no native MCP picker): add the connector under **Advanced > Tools > MCP** and paste the **MCP Endpoint** URL. Newer Agent Factory agents use the native capability picker described above.
## Available Tools
### System & Authentication
| Tool | Description |
| ------------------------ | -------------------------- |
| `validateAuthentication` | Validate the current token |
| `getServerVersion` | Get SonarQube version |
| `listLanguages` | List supported languages |
### Organizations
| Tool | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `searchOrganizations` | List SonarCloud organizations visible to the token. **Pass `member: true` for your own orgs, or `organizations` to check specific keys** — use the returned `key` as the `organization` argument elsewhere |
### Projects
| Tool | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `searchProjects` | Search projects you administer (filter by `q`, `qualifiers`, `visibility`, `analyzedBefore`). **Admin-scoped — for public orgs use `searchPublicProjects`** |
| `searchPublicProjects` | Browse projects in any org, including public orgs you are not a member of (Project Explorer endpoint) |
| `createProject` | Create a project |
| `deleteProject` | Delete a project |
| `updateProjectKey` | Update the project key |
| `updateProjectVisibility` | Change project visibility |
### Components
| Tool | Description |
| ------------------ | ----------------------------------------------- |
| `showComponent` | Describe a component (project, file, directory) |
| `searchComponents` | Search components (projects, files) |
| `getComponentTree` | Navigate the component tree |
### Issues
| Tool | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `searchIssues` | Search for issues. **For "my issues / mes issues" pass `assignees: __me__`** (or `author: __me__` for issues you reported). To filter unresolved, pass `statuses: OPEN,CONFIRMED,REOPENED` |
| `assignIssue` | Assign or unassign an issue (omit `assignee` to unassign) |
| `transitionIssue` | Perform a workflow transition on an issue |
| `addIssueComment` | Add a comment to an issue |
| `setIssueTags` | Set tags on an issue (comma-separated; empty to clear) |
| `setIssueSeverity` | Change the severity of an issue |
| `setIssueType` | Change the type of an issue |
### Measures & Metrics
| Tool | Description |
| -------------------------- | -------------------------------------------------------- |
| `getComponentMeasures` | Get measures of a component (e.g. `ncloc,bugs,coverage`) |
| `getComponentTreeMeasures` | Get measures for a component tree |
| `getMeasuresHistory` | Get history of measures over a period |
| `searchMetrics` | Search metric definitions |
### Quality Gates
| Tool | Description |
| ----------------------------- | ------------------------------------------------------ |
| `listQualityGates` | List quality gates |
| `showQualityGate` | Show a quality gate (by `id` or `name`) |
| `getProjectQualityGateStatus` | Get the quality-gate status of a project / branch / PR |
| `selectQualityGate` | Associate a project with a quality gate |
### Quality Profiles & Rules
| Tool | Description |
| ----------------------- | ----------------------- |
| `searchQualityProfiles` | Search quality profiles |
| `searchRules` | Search rules |
| `showRule` | Show a rule |
### Hotspots
| Tool | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| `searchHotspots` | Search security hotspots. **For "my hotspots" pass `onlyMine: true`. For unresolved pass `status: TO_REVIEW`** |
| `showHotspot` | Show a security hotspot |
| `changeHotspotStatus` | Change the status of a hotspot |
### User Tokens
| Tool | Description |
| ------------------- | --------------------------------------------------------------------------------------- |
| `searchUserTokens` | List user tokens (admin-only when `login` targets another user) |
| `generateUserToken` | Generate a user token (`USER_TOKEN`, `PROJECT_ANALYSIS_TOKEN`, `GLOBAL_ANALYSIS_TOKEN`) |
| `revokeUserToken` | Revoke a user token by name |
### Analyses & Branches
| Tool | Description |
| ----------------------- | ------------------------------------- |
| `searchProjectAnalyses` | Search project analyses |
| `createAnalysisEvent` | Create an event on a project analysis |
| `listProjectBranches` | List branches of a project |
| `deleteProjectBranch` | Delete a branch from a project |
### Webhooks
| Tool | Description |
| --------------- | ------------------------------------- |
| `listWebhooks` | List webhooks (global or per-project) |
| `createWebhook` | Create a webhook |
| `deleteWebhook` | Delete a webhook |
### Badges
| Tool | Description |
| ---------------------------- | ---------------------------------------------------- |
| `getProjectMeasureBadge` | Get an SVG badge for a project metric |
| `getProjectQualityGateBadge` | Get an SVG badge for the project quality-gate status |
## Output Formats
Every tool accepts an `outputFormat` argument that controls the MCP response shape:
* **`verbose`** (default) — human-readable text for LLM consumption
* **`structured`** — machine-readable JSON in `structuredContent`
* **`both`** — both text and structured content
## Tool Details
### searchIssues
Search and filter issues on a project. Default response includes all issues the token can see; combine filters to scope down.
```json theme={null}
{
"name": "searchIssues",
"arguments": {
"componentKeys": "my_org_my-project",
"types": "BUG,VULNERABILITY",
"severities": "CRITICAL,BLOCKER",
"statuses": "OPEN,CONFIRMED,REOPENED",
"branch": "main",
"ps": 100
}
}
```
| Parameter | Required | Description |
| -------------------------------- | -------- | ------------------------------------------------- |
| `componentKeys` | No | Comma-separated component / project keys |
| `assignees` | No | Use `__me__` for the current user |
| `severities` | No | `INFO`,`MINOR`,`MAJOR`,`CRITICAL`,`BLOCKER` |
| `types` | No | `BUG`,`VULNERABILITY`,`CODE_SMELL` |
| `statuses` | No | `OPEN`,`CONFIRMED`,`REOPENED`,`RESOLVED`,`CLOSED` |
| `tags` | No | Comma-separated tag names |
| `createdAfter` / `createdBefore` | No | ISO date or `YYYY-MM-DD` |
| `branch` / `pullRequest` | No | Restrict to a branch or PR |
| `p` / `ps` | No | Pagination — `ps` max 500 |
### searchOrganizations
Discover the SonarCloud organization keys your token can see — call this first when you do not know the `organization` value other tools require.
```json theme={null}
{
"name": "searchOrganizations",
"arguments": {
"member": true
}
}
```
| Parameter | Required | Description |
| --------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `member` | No\* | When `true`, return only orgs the authenticated user belongs to |
| `organizations` | No\* | Comma-separated org keys to check (one of `member` or `organizations` is required on SonarCloud) |
| `p` / `ps` | No | Pagination |
### transitionIssue
Move an issue through SonarQube's workflow.
```json theme={null}
{
"name": "transitionIssue",
"arguments": {
"issue": "AY9z...",
"transition": "falsepositive"
}
}
```
| Parameter | Required | Description |
| ------------ | -------- | -------------------------------------------------------------------------------- |
| `issue` | Yes | Issue key |
| `transition` | Yes | `confirm`, `unconfirm`, `reopen`, `resolve`, `falsepositive`, `wontfix`, `close` |
### getComponentMeasures
Read one or several metric values for a component (project, file, directory).
```json theme={null}
{
"name": "getComponentMeasures",
"arguments": {
"component": "my_org_my-project",
"metricKeys": "ncloc,bugs,vulnerabilities,coverage,duplicated_lines_density",
"branch": "main"
}
}
```
| Parameter | Required | Description |
| ------------------ | -------- | ------------------------------------------------- |
| `component` | Yes | Component key (project, file or directory) |
| `metricKeys` | Yes | Comma-separated metric keys — see `searchMetrics` |
| `branch` | No | Branch name |
| `pullRequest` | No | Pull request ID |
| `additionalFields` | No | Extra fields (e.g. `metrics,periods`) |
### getProjectQualityGateStatus
Useful as a one-shot pass/fail check for CI gates.
```json theme={null}
{
"name": "getProjectQualityGateStatus",
"arguments": {
"projectKey": "my_org_my-project",
"branch": "main"
}
}
```
| Parameter | Required | Description |
| ------------- | -------- | ------------------------------------------------------------ |
| `projectKey` | No\* | Project key (one of `projectKey` or `projectId` must be set) |
| `projectId` | No\* | Project ID — alternative to `projectKey` |
| `branch` | No | Restrict to a branch |
| `pullRequest` | No | Restrict to a pull request |
### createProject
Provision a new project. On SonarCloud, `organization` is required.
```json theme={null}
{
"name": "createProject",
"arguments": {
"name": "Website Revamp",
"project": "my_org_website-revamp",
"organization": "my_org",
"visibility": "private"
}
}
```
| Parameter | Required | Description |
| -------------- | -------- | ------------------------------------------- |
| `name` | Yes | Display name |
| `project` | Yes | Project key (unique, alphanumeric + `-_.:`) |
| `organization` | No\* | Required on SonarCloud |
| `visibility` | No | `public` or `private` |
## Workspace builder
**Goal:** install the connector in a workspace, configure the SonarQube credential, and call SonarQube operations from your automations.
## Installation
1. Go to **Apps** in your workspace
2. Search for **SonarQube** and install it
3. Open the app instance configuration and fill in the required fields
## Configuration
| Field | Description |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **SonarQube API Base URL** | Base URL of the SonarQube API. Defaults to `https://sonarcloud.io/api` — replace with your self-hosted instance URL when applicable |
| **API Token** | SonarQube User Token, stored as a workspace secret. Passed server-side as `Authorization: Bearer ` |
| **MCP Endpoint** | Auto-populated on install — the URL of the MCP endpoint for this instance (used to wire the *Agent builder* capability) |
| Auth mode | What you provide | Best for |
| ------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| User Token (Bearer) | A SonarQube **User Token** + the **API base URL** | Standard setup — the token is stored as a workspace secret and resolved server-side on every call |
SonarQube identifiers are project keys, component keys, issue keys, rule keys and login names — never numeric IDs except for quality-gate `gateId`. Most list / search operations accept `p` (page index, 1-based) and `ps` (page size, max 500) for pagination. On SonarCloud, most search and create operations also require an `organization` key.
## Available Instructions
Every instruction resolves credentials from the workspace configuration.
### System & Authentication
| Instruction | Description | Returns |
| ------------------------ | ------------------------------------------------------ | -------------------------------- |
| `validateAuthentication` | Validate the current token against the instance. | `{ valid }` |
| `getServerVersion` | Get the SonarQube server version. | A version string |
| `listLanguages` | List supported languages; optional `q` filter on name. | `{ languages: [{ key, name }] }` |
### Organizations
| Instruction | Description | Returns |
| --------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `searchOrganizations` | List SonarCloud organizations visible to the token; pass `member: true` or `organizations`. | `{ organizations: [{ key, name, description, url }], paging }` |
### Projects
| Instruction | Description | Returns |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `searchProjects` | Search projects you administer; filter by `organization`, `projects`, `q`, `qualifiers`, `visibility`, `analyzedBefore`, `onProvisionedOnly`. | `{ components: [{ key, name, visibility }], paging }` |
| `searchPublicProjects` | Browse projects in any org (incl. public orgs you are not a member of) by `organization`, optional `filter`/`s`/`asc`. | `{ projects: [{ key, name }], paging }` |
| `createProject` | Create a project from `name` + `project` (key); `organization` required on SonarCloud; optional `visibility`. | `{ project: { key, name, visibility } }` |
| `deleteProject` | Delete a project by `project` key. | Empty (HTTP 204) |
| `updateProjectKey` | Rename a project key `from` → `to`. | Empty (HTTP 204) |
| `updateProjectVisibility` | Set `visibility` (`public`/`private`) on a `project`. | Empty (HTTP 204) |
### Components
| Instruction | Description | Returns |
| ------------------ | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `showComponent` | Describe a `component` (project, file, directory); optional `branch`/`pullRequest`. | `{ component: { key, name, qualifier } }` |
| `searchComponents` | Search components by `q`, `qualifiers` (`TRK`,`FIL`,`DIR`…), `organization`. | `{ components: [{ key, name, qualifier }], paging }` |
| `getComponentTree` | Navigate the tree under `component`; `strategy` (`children`/`all`/`leaves`), `qualifiers`, `q`, `branch`, `s`. | `{ baseComponent, components: [{ key, name }], paging }` |
### Issues
| Instruction | Description | Returns |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `searchIssues` | Search issues by `componentKeys`, `projects`, `assignees`, `author`, `severities`, `types`, `statuses`, `resolutions`, `resolved`, `tags`, `createdAfter`/`createdBefore`, `languages`, `rules`, `branch`/`pullRequest`. | `{ issues: [{ key, rule, severity, type, status, component }], paging }` |
| `assignIssue` | Assign `issue` to `assignee` (omit `assignee` to unassign). | `{ issue }` |
| `transitionIssue` | Apply `transition` (`confirm`/`reopen`/`resolve`/`falsepositive`/`wontfix`/`close`…) to `issue`. | `{ issue }` |
| `addIssueComment` | Add `text` comment to `issue`. | `{ issue, comment }` |
| `setIssueTags` | Set comma-separated `tags` on `issue` (empty clears). | `{ issue }` |
| `setIssueSeverity` | Set `severity` (`INFO`…`BLOCKER`) on `issue`. | `{ issue }` |
| `setIssueType` | Set `type` (`BUG`/`VULNERABILITY`/`CODE_SMELL`) on `issue`. | `{ issue }` |
### Measures & Metrics
| Instruction | Description | Returns |
| -------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `getComponentMeasures` | Read `metricKeys` for a `component`; optional `branch`/`pullRequest`/`additionalFields`. | `{ component: { measures: [{ metric, value }] } }` |
| `getComponentTreeMeasures` | Read `metricKeys` across the tree under `component`; `strategy`, `qualifiers`, `s`. | `{ baseComponent, components: [{ measures }], paging }` |
| `getMeasuresHistory` | History of `metrics` for `component` over `from`/`to`. | `{ measures: [{ metric, history: [{ date, value }] }], paging }` |
| `searchMetrics` | Search metric definitions; optional fields `f`. | `{ metrics: [{ key, name, type }], total }` |
### Quality Gates
| Instruction | Description | Returns |
| ----------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------- |
| `listQualityGates` | List quality gates; optional `organization`. | `{ qualitygates: [{ id, name }], default }` |
| `showQualityGate` | Show a gate by `id` or `name`. | `{ id, name, conditions: [{ metric, op, error }] }` |
| `getProjectQualityGateStatus` | Pass/fail status for `projectKey`/`projectId`; optional `branch`/`pullRequest`. | `{ projectStatus: { status, conditions: [...] } }` |
| `selectQualityGate` | Associate `projectKey` with a gate (`gateId`/`gateName`). | Empty (HTTP 204) |
### Quality Profiles & Rules
| Instruction | Description | Returns |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `searchQualityProfiles` | Search profiles by `organization`, `language`, `project`, `qualityProfile`, `defaults`. | `{ profiles: [{ key, name, language }] }` |
| `searchRules` | Search rules by `q`, `languages`, `repositories`, `severities`, `types`, `tags`, `statuses`, `qprofile`, `activation`. | `{ rules: [{ key, name, severity }], total }` |
| `showRule` | Show a rule by `key`; optional `organization`. | `{ rule: { key, name, htmlDesc } }` |
### Hotspots
| Instruction | Description | Returns |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `searchHotspots` | Search hotspots by `projectKey`, `branch`/`pullRequest`, `status` (`TO_REVIEW`/`REVIEWED`), `resolution`, `onlyMine`, `sinceLeakPeriod`. | `{ hotspots: [{ key, status, vulnerabilityProbability }], paging }` |
| `showHotspot` | Show a hotspot by `hotspot` key. | `{ key, status, rule, component }` |
| `changeHotspotStatus` | Set `status` on `hotspot`; optional `resolution`, `comment`. | Empty (HTTP 204) |
### User Tokens
| Instruction | Description | Returns |
| ------------------- | ---------------------------------------------------------------------------------- | --------------------------------------- |
| `searchUserTokens` | List user tokens; optional `login` (admin-only for other users). | `{ userTokens: [{ name, createdAt }] }` |
| `generateUserToken` | Generate a token `name`; optional `login`, `type`, `projectKey`, `expirationDate`. | `{ name, token, type }` |
| `revokeUserToken` | Revoke a token by `name`; optional `login`. | Empty (HTTP 204) |
### Analyses & Branches
| Instruction | Description | Returns |
| ----------------------- | -------------------------------------------------------------------------- | ----------------------------------------------- |
| `searchProjectAnalyses` | Search analyses for `project`; optional `branch`, `category`, `from`/`to`. | `{ analyses: [{ key, date, events }], paging }` |
| `createAnalysisEvent` | Add `name` event (`category` `VERSION`/`OTHER`) to `analysis`. | `{ event: { key, name, category } }` |
| `listProjectBranches` | List branches of `project`. | `{ branches: [{ name, type, status }] }` |
| `deleteProjectBranch` | Delete `branch` from `project`. | Empty (HTTP 204) |
### Webhooks
| Instruction | Description | Returns |
| --------------- | ---------------------------------------------------------------------------- | ------------------------------------ |
| `listWebhooks` | List webhooks; optional `organization`/`project`. | `{ webhooks: [{ key, name, url }] }` |
| `createWebhook` | Create webhook `name` + `url`; optional `organization`, `project`, `secret`. | `{ webhook: { key, name, url } }` |
| `deleteWebhook` | Delete a webhook by `webhook` key. | Empty (HTTP 204) |
### Badges
| Instruction | Description | Returns |
| ---------------------------- | ------------------------------------------------------------------------------- | ---------------- |
| `getProjectMeasureBadge` | SVG badge for `project` + `metric`; optional `branch`, `token`. | Raw SVG document |
| `getProjectQualityGateBadge` | SVG badge for the quality-gate status of `project`; optional `branch`, `token`. | Raw SVG document |
`Returns` shows the shape of the operation output. Arguments noted with `*` in the *Agent builder* tool details are required; on SonarCloud, pass `organization` explicitly or default it in your automation.
## DSUL Examples
### List all unresolved bugs on a project
```yaml theme={null}
- SonarQube.searchIssues:
componentKeys: '{{projectKey}}'
types: BUG
statuses: OPEN,CONFIRMED,REOPENED
ps: 100
output: issues
```
### Get the quality-gate status of a branch
```yaml theme={null}
- SonarQube.getProjectQualityGateStatus:
projectKey: '{{projectKey}}'
branch: main
output: gateStatus
- conditions:
'{{gateStatus.projectStatus.status}} == "ERROR"':
- emit:
event: qualityGateFailed
payload:
project: '{{projectKey}}'
conditions: '{{gateStatus.projectStatus.conditions}}'
```
### Triage a flaky issue as false positive
```yaml theme={null}
- SonarQube.transitionIssue:
issue: '{{issueKey}}'
transition: falsepositive
- SonarQube.addIssueComment:
issue: '{{issueKey}}'
text: 'False positive — already addressed in {{commitSha}}'
```
### Pull last week's coverage and bugs trend
```yaml theme={null}
- SonarQube.getMeasuresHistory:
component: '{{projectKey}}'
metrics: coverage,bugs,vulnerabilities,code_smells
from: '{{lastWeekIso}}'
ps: 1000
output: history
```
### Provision a new SonarCloud project
```yaml theme={null}
- SonarQube.createProject:
name: '{{repoName}}'
project: '{{org}}_{{repoName}}'
organization: '{{org}}'
visibility: private
output: project
- SonarQube.selectQualityGate:
projectKey: '{{project.project.key}}'
gateName: 'Sonar way'
organization: '{{org}}'
```
***
## Error Handling
| HTTP Status | Error | Solution |
| ----------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| 400 | Bad Request | Verify required arguments — on SonarCloud, most operations need `organization` (discover it with `searchOrganizations`) |
| 401 | Unauthorized | Verify the User Token and `baseUrl` |
| 403 | Forbidden | Check the SonarQube permissions of the token owner (admin-only operations such as `searchUserTokens` for other users) |
| 404 | Not Found | Verify project keys, component keys, issue keys and login names |
| 409 | Conflict | Resource already exists (project key, token name, …) — pick a different identifier |
| 429 | Rate Limited | Back off and retry with exponential delay |
| 500 | Server Error | Server-side issue — check SonarQube logs (self-hosted) or SonarCloud status |
### Common Issues
**"Not configured"** — The app instance has no User Token. Generate one in *SonarQube > My Account > Security > Generate Tokens* and paste it in the app configuration (see the *Workspace builder* tab).
**"Invalid credentials"** — SonarQube rejected the token (revoked, expired or wrong instance). Re-generate the User Token and re-paste it, and confirm the **API base URL** matches your instance (SonarCloud vs self-hosted).
**"organization parameter is missing"** — On SonarCloud, most search and create operations require the `organization` key. Pass it explicitly in the tool arguments or as a default in your DSUL automation; call `searchOrganizations` to discover the keys your token can see.
**`searchProjects` returns nothing on a public org** — `searchProjects` is admin-scoped (it only lists projects in organizations you administer). To browse projects in any organization, including public ones you are not a member of, use `searchPublicProjects`.
**Badge tools return non-SVG content** — `getProjectMeasureBadge` and `getProjectQualityGateBadge` return raw SVG. The MCP transport currently surfaces them as JSON-encoded strings; consume them in App mode (DSUL) to write the SVG straight to a file or HTTP response.
## External Resources
Official SonarQube Web API reference
SonarCloud-flavored Web API reference
Product documentation, metrics catalog, rule descriptions
Learn how Agent Factory agents consume MCP tools in Prisme.ai.