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
- SonarCloud:
- For SonarCloud only: the organization key that owns your projects (most search and create operations require it — use
searchOrganizationsto discover the keys visible to your token).
Platform admin (Governance) — one-time platform setup
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)
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:The
agent_id in the scope is what lets the connector identify the calling agent.- Agent builder (Agent Factory)
- Workspace builder (DSUL)
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).
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.
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:The server URL and identity propagation are then wired; the SonarQube token is fetched server-side from the app configuration.
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: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 anoutputFormat argument that controls the MCP response shape:verbose(default) — human-readable text for LLM consumptionstructured— machine-readable JSON instructuredContentboth— 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.| 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 theorganization value other tools require.| 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.| 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).| 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.| 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.| Parameter | Required | Description |
|---|---|---|
name | Yes | Display name |
project | Yes | Project key (unique, alphanumeric + -_.:) |
organization | No* | Required on SonarCloud |
visibility | No | public or private |
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 theorganization 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.