Skip to main content
SonarQube 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).
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

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

ToolDescription
validateAuthenticationValidate the current token
getServerVersionGet SonarQube version
listLanguagesList supported languages

Organizations

ToolDescription
searchOrganizationsList 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

ToolDescription
searchProjectsSearch projects you administer (filter by q, qualifiers, visibility, analyzedBefore). Admin-scoped — for public orgs use searchPublicProjects
searchPublicProjectsBrowse projects in any org, including public orgs you are not a member of (Project Explorer endpoint)
createProjectCreate a project
deleteProjectDelete a project
updateProjectKeyUpdate the project key
updateProjectVisibilityChange project visibility

Components

ToolDescription
showComponentDescribe a component (project, file, directory)
searchComponentsSearch components (projects, files)
getComponentTreeNavigate the component tree

Issues

ToolDescription
searchIssuesSearch 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
assignIssueAssign or unassign an issue (omit assignee to unassign)
transitionIssuePerform a workflow transition on an issue
addIssueCommentAdd a comment to an issue
setIssueTagsSet tags on an issue (comma-separated; empty to clear)
setIssueSeverityChange the severity of an issue
setIssueTypeChange the type of an issue

Measures & Metrics

ToolDescription
getComponentMeasuresGet measures of a component (e.g. ncloc,bugs,coverage)
getComponentTreeMeasuresGet measures for a component tree
getMeasuresHistoryGet history of measures over a period
searchMetricsSearch metric definitions

Quality Gates

ToolDescription
listQualityGatesList quality gates
showQualityGateShow a quality gate (by id or name)
getProjectQualityGateStatusGet the quality-gate status of a project / branch / PR
selectQualityGateAssociate a project with a quality gate

Quality Profiles & Rules

ToolDescription
searchQualityProfilesSearch quality profiles
searchRulesSearch rules
showRuleShow a rule

Hotspots

ToolDescription
searchHotspotsSearch security hotspots. For “my hotspots” pass onlyMine: true. For unresolved pass status: TO_REVIEW
showHotspotShow a security hotspot
changeHotspotStatusChange the status of a hotspot

User Tokens

ToolDescription
searchUserTokensList user tokens (admin-only when login targets another user)
generateUserTokenGenerate a user token (USER_TOKEN, PROJECT_ANALYSIS_TOKEN, GLOBAL_ANALYSIS_TOKEN)
revokeUserTokenRevoke a user token by name

Analyses & Branches

ToolDescription
searchProjectAnalysesSearch project analyses
createAnalysisEventCreate an event on a project analysis
listProjectBranchesList branches of a project
deleteProjectBranchDelete a branch from a project

Webhooks

ToolDescription
listWebhooksList webhooks (global or per-project)
createWebhookCreate a webhook
deleteWebhookDelete a webhook

Badges

ToolDescription
getProjectMeasureBadgeGet an SVG badge for a project metric
getProjectQualityGateBadgeGet 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
  }
}
ParameterRequiredDescription
componentKeysNoComma-separated component / project keys
assigneesNoUse __me__ for the current user
severitiesNoINFO,MINOR,MAJOR,CRITICAL,BLOCKER
typesNoBUG,VULNERABILITY,CODE_SMELL
statusesNoOPEN,CONFIRMED,REOPENED,RESOLVED,CLOSED
tagsNoComma-separated tag names
createdAfter / createdBeforeNoISO date or YYYY-MM-DD
branch / pullRequestNoRestrict to a branch or PR
p / psNoPagination — 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
  }
}
ParameterRequiredDescription
memberNo*When true, return only orgs the authenticated user belongs to
organizationsNo*Comma-separated org keys to check (one of member or organizations is required on SonarCloud)
p / psNoPagination

transitionIssue

Move an issue through SonarQube’s workflow.
{
  "name": "transitionIssue",
  "arguments": {
    "issue": "AY9z...",
    "transition": "falsepositive"
  }
}
ParameterRequiredDescription
issueYesIssue key
transitionYesconfirm, 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"
  }
}
ParameterRequiredDescription
componentYesComponent key (project, file or directory)
metricKeysYesComma-separated metric keys — see searchMetrics
branchNoBranch name
pullRequestNoPull request ID
additionalFieldsNoExtra 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"
  }
}
ParameterRequiredDescription
projectKeyNo*Project key (one of projectKey or projectId must be set)
projectIdNo*Project ID — alternative to projectKey
branchNoRestrict to a branch
pullRequestNoRestrict 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"
  }
}
ParameterRequiredDescription
nameYesDisplay name
projectYesProject key (unique, alphanumeric + -_.:)
organizationNo*Required on SonarCloud
visibilityNopublic or private

Error Handling

HTTP StatusErrorSolution
400Bad RequestVerify required arguments — on SonarCloud, most operations need organization (discover it with searchOrganizations)
401UnauthorizedVerify the User Token and baseUrl
403ForbiddenCheck the SonarQube permissions of the token owner (admin-only operations such as searchUserTokens for other users)
404Not FoundVerify project keys, component keys, issue keys and login names
409ConflictResource already exists (project key, token name, …) — pick a different identifier
429Rate LimitedBack off and retry with exponential delay
500Server ErrorServer-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 orgsearchProjects 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 contentgetProjectMeasureBadge 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.