> 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/sonarqube-mcp-server/setup/sonarqube-cloud-hosted.md).

# SonarQube Cloud-hosted

The SonarQube Cloud-hosted configuration ensures you use the most up to date version of the SonarQube MCP Server and gives you access to a subset of tools.

To always use the most up-to-date version of the SonarQube MCP Server, connect directly to the SonarQube Cloud-hosted MCP server. No local setup is required.

Use the SonarQube MCP server embedded in SonarQube Cloud to avoid running and maintaining your own MCP infrastructure while always using the current server version. The embedded server exposes a smaller, fixed subset of tools.

> **Note:** If you use SonarQube for IDE, its **AI Integrations** setup workflow only configures a self-hosted MCP server. See [Manual setup](#manual-setup) to connect to this Cloud-hosted MCP server instead.

![Use the SonarQube Cloud-hosted MCP server to connect your MCP client directly to the SonarQube Cloud API.](https://2704720390-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNMPi6OcwuaQpPV3mp3TU%2Fuploads%2Fgit-blob-ed367ba75ca39c32d9b40161e0f001e6a28a3909%2Fsonarqube-mcp-server-embedded.png?alt=media)

## Sign in with OAuth

Sonar's hosted SonarQube Cloud MCP service accepts OAuth alongside SonarQube tokens. Use one of the [supported OAuth clients](#supported-oauth-clients) and sign in when prompted. You do not add OAuth server settings to the client configuration. Existing SonarQube token clients keep working.

Point the client at `https://api.sonarcloud.io/mcp`. For a US-region organization, use `https://api.sonarqube.us/mcp`.

The `mcp:tools:read` and `mcp:tools:write` scopes independently control access to read and write tools, subject to your Cloud permissions. A call outside those scopes fails with `Insufficient OAuth scope`.

Select an organization with [`list_organizations`](/sonarqube-mcp-server/reference/tools.md#projects), then pass that key as `organization` on the tool call. An OAuth request that includes a `SONARQUBE_ORG` header fails with `SONARQUBE_ORG is not supported for OAuth requests. Use the tool organization argument.`

Self-hosted deployments continue to use SonarQube tokens. OAuth for SonarQube Server is not supported yet.

### Supported OAuth clients

OAuth sign-in with the SonarQube Cloud-hosted MCP server requires your client to use Client ID Metadata Documents (CIMD). A CIMD is a public document that identifies an OAuth client. Sonar must also approve the client's metadata URL.

The following clients are approved for OAuth sign-in:

* ChatGPT
* Claude (claude.ai)
* Claude Code
* Codex
* Cursor
* GitHub Copilot desktop
* Visual Studio Code
* Zed

Use a version of your client that supports CIMD. This list covers OAuth sign-in only. A client that sends a SonarQube user token in an Authorization header does not need to be listed.

### If your client is not listed

If your client is not listed, check its documentation or ask its vendor whether it supports CIMD for MCP OAuth:

* If it supports CIMD, request its addition to Sonar's allowlist through the [Sonar Community MCP category](https://community.sonarsource.com/c/mcp/54). Include the client name, version, and public metadata URL or vendor documentation. Sonar reviews each request before approving a client.
* If it does not support CIMD, ask the client vendor to add it. Sonar cannot enable OAuth for that client through allowlisting alone.

If your client supports Streamable HTTP and custom authorization headers, [connect with a SonarQube user token](#manual-setup) instead.

## Use the configuration generator

Use the official SonarQube MCP Server configuration generator to get a SonarQube token configuration snippet. For OAuth, see [Sign in with OAuth](#sign-in-with-oauth). To use the generator:

1. Identify your agent.
2. Find your [common variables](/sonarqube-mcp-server/reference/environment-variables.md#common-variables).
3. Enter the information into the [SonarQube MCP Server configuration generator](https://mcp.sonarqube.com/config-generator.html) with the SonarQube Cloud (embedded) configuration.
4. Paste the generated configuration into your configuration file.

## Manual setup

Use this configuration when the client authenticates with a SonarQube user token. To sign in with OAuth instead, see [Sign in with OAuth](#sign-in-with-oauth).

Add this configuration to your mcp.json file in your AI-enabled client config folder.

```jsonc
"sonarqube": {
  "type": "http",
  "url": "https://api.sonarcloud.io/mcp",
  "headers": {
    "Authorization": "Bearer <YourSonarQubeUserToken>",
    "SONARQUBE_ORG": "<YourSonarQubeOrganization>"
    // "SONARQUBE_READ_ONLY": "true" // Default value is false.
    // "SONARQUBE_TOOLSETS": "<YourOptionalToolset>" // Using this optional header refines the default toolsets.
  }
}
```

> **Note:** For a SonarQube token, `SONARQUBE_ORG` is optional. Set the header to fix the organization for that request, or omit it and pass `organization` on organization-aware tools. OAuth requests reject this header. See [SONARQUBE\_ORG](/sonarqube-mcp-server/reference/environment-variables.md#sonarqube_org) and [Sign in with OAuth](#sign-in-with-oauth).

> **Note:** Replace your `"url"` with `https://api.sonarqube.us/mcp` if you're connecting to a SonarQube Cloud organization in the US region.

Optional headers include:

* SONARQUBE\_READ\_ONLY: Boolean. Set to `true` to enable read-only mode or `false` to allow write operations (default).
* SONARQUBE\_TOOLSETS: Comma-separated list of toolsets that limits the tools your agent can use. For the supported keys, see [Tool availability with SonarQube Cloud](#tool-availability-with-sonarqube-cloud).

> **Warning:** Using the optional headers replaces the default configuration. For example, when you add `"SONARQUBE_TOOLSETS": "issues,projects"`, you will not load the `security-hotspots` and `quality-gates` toolsets.

### Tool availability with SonarQube Cloud

When you use the SonarQube MCP Server through SonarQube Cloud, you get a smaller, fixed set of tools compared to running the MCP Server yourself. This is by design and cannot be changed:

* Heavy analysis tools are disabled to protect the shared SonarQube Cloud infrastructure.
* [Sonar Vortex](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex.md) analysis and context are not available because they require a local filesystem mount, which the hosted environment cannot provide. To use Sonar Vortex, set up a local MCP Server using [Stdio](/sonarqube-mcp-server/setup/self-hosted.md#local-server-stdio). The recommended methods are the SonarQube plugin or SonarQube CLI; see the [Sonar Vortex analysis](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) and [Sonar Vortex context](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) pages.
* SonarQube for IDE bridge tools (`analyze_file_list` and `toggle_automatic_analysis`) are not available because the hosted environment cannot reach SonarQube for IDE on your machine. To use them, set up a local MCP Server using [Stdio](/sonarqube-mcp-server/setup/self-hosted.md#local-server-stdio).
* Rarely used, non-default tools are excluded to keep the MCP context small and focused.

The embedded MCP server includes a default list of toolsets. Define a subset of this list using the `SONARQUBE_TOOLSETS` header:

* `analysis`,`coverage`,`dependency-risks`,`duplications`,`issues`,`measures`,`projects`,`quality-gates`,`rules`,`security-hotspots`

For the tools in each toolset, see the [Tools](/sonarqube-mcp-server/reference/tools.md) page.

For the complete list of tools supported by a self-hosted SonarQube MCP Server, see the [Tools](/sonarqube-mcp-server/reference/tools.md) page.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-mcp-server/setup/sonarqube-cloud-hosted.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.