SonarQube

Read and act on SonarQube / SonarQube Cloud code-quality data from Agent Factory agents and Builder workflows

The SonarQube app exposes the SonarQube and SonarQube Cloud 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.

Code Quality

Issues, security hotspots, rules and quality profiles to triage code findings.

Project Insights

Measures, metric definitions, history, quality-gate status and analyses.

Admin & Operations

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.

Agent builder

You build agents in Agent Factory and want them to use SonarQube. → Agent builder tab.

Platform admin

You run the platform and set up SonarQube once for everyone. → Platform admin setup accordion below.

Workspace builder

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 <token>).
• The API base URL of your instance:
  • SonarCloud: https://sonarcloud.io/api
  • Self-hosted: https://<your-sonarqube-host>/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).

Platform admin (Governance) — one-time platform setup

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)

1. Open AI Governance > Capabilities

   Create (or edit) the SonarQube capability.

2. Point it at the MCP endpoint

   Set the capability’s MCP server URL to the connector’s MCP Endpoint (the workspace running the connector), and set its Scope to:

   context_id,agent_id,user_id
   

   The agent_id in the scope is what lets the connector identify the calling agent.

3. Make it available to agent builders

   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 (Agent Factory)

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.

1. Install and configure the connector in a workspace

   Follow the Workspace builder tab: install SonarQube in your workspace and provide the API base URL and User Token.

2. Add the MCP capability to your agent

   In your agent, add a capability pointing at the workspace’s MCP Endpoint URL, and set its Scope to:

   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.

3. Brief the agent in its system prompt

   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:

   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.

{
  "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.

{
  "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.

{
  "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).

{
  "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.

{
  "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.

{
  "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 (DSUL)

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 <token>
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

- SonarQube.searchIssues:
    componentKeys: '{{projectKey}}'
    types: BUG
    statuses: OPEN,CONFIRMED,REOPENED
    ps: 100
    output: issues

Get the quality-gate status of a branch

- 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

- 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

- SonarQube.getMeasuresHistory:
    component: '{{projectKey}}'
    metrics: coverage,bugs,vulnerabilities,code_smells
    from: '{{lastWeekIso}}'
    ps: 1000
    output: history

Provision a new SonarCloud project

- 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

SonarQube Web API

Official SonarQube Web API reference

SonarCloud Web API

SonarCloud-flavored Web API reference

SonarSource Documentation

Product documentation, metrics catalog, rule descriptions

Tool Agents

Learn how Agent Factory agents consume MCP tools in Prisme.ai.