# Configure your SonarQube MCP server No matter if you're looking for a configuration for single-users ([#stdio](#stdio "mention")), multi-user ([#http](#http "mention")), or secure multi-client ([#https](#https "mention")) configurations, the SonarQube MCP Server has you covered. On this page, you'll find container image examples for setup with SonarQube Cloud and SonarQube Server, including requirements for user tokens and handling of custom certificates and proxies. If you're unable to use a container image to deploy your MCP server, please see the [build](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/build "mention") page for alternatives. ## Overview The SonarQube MCP Server uses [#stdio](#stdio "mention") when running a local configuration. This configuration is designed for single-user access however, it's possible to manage your MCP server using a [#transport-mode](#transport-mode "mention") configuration, designed for shared access across a network using [#http](#http "mention") or [#https](#https "mention") connection protocols. ## Connecting to SonarQube Cloud in the US region Connecting your SonarQube MCP Server with your SonarQube Cloud US instance requires the use of common variable, defined as `SONARQUBE_URL=https://sonarqube.us` in your configuration file. See the [#common-variables](https://docs.sonarsource.com/sonarqube-mcp-server/environment-variables#common-variables "mention") table for details about the parameter. Where possible, each of the code samples given in the [#mcp-server-setup-in-your-ide](https://docs.sonarsource.com/sonarqube-mcp-server/quickstart-guide#mcp-server-setup-in-your-ide "mention") quickstart guides will include an example to configure SONARQUBE\_URL when connecting to a SonarQube Cloud organization in the US region. For full details about SonarQube Cloud accounts hosted in the US region, see the [Getting started in the US region](https://app.gitbook.com/s/B4UT2GNiZKjtxFtcFAL7/getting-started/getting-started-in-us-region "mention") page. ### MCP Server in SonarQube Cloud To always use the most up to date version of the SonarQube MCP Server, connect directly to SonarQube Cloud's embedded server. Check SonarQube Cloud's [SonarQube MCP Server #Setting up a local MCP Server](https://app.gitbook.com/s/B4UT2GNiZKjtxFtcFAL7/ai-capabilities/sonarqube-mcp-server#setting-up-the-sonarqube-server-with-docker "mention") page for the complete configuration details. ## Agentic Analysis and Context Augmentation When using SonarQube Cloud's Agentic Analysis and Context Augmentation services, your `SONARQUBE_TOKEN` will allow your local MCP server configured for [#stdio](#stdio "mention") mode to authenticate to the SonarQube Cloud API. See the SonarQube Cloud pages [Agentic Analysis](https://app.gitbook.com/s/B4UT2GNiZKjtxFtcFAL7/analyzing-source-code/agentic-analysis "mention") and [Context Augmentation](https://app.gitbook.com/s/B4UT2GNiZKjtxFtcFAL7/analyzing-source-code/context-augmentation "mention") to get the correct configuration details. ## Transport mode Once configured, your MCP server is hosted on a local network and can handle connections from multiple users; all of your team's developers can access the same MCP server and reduces the need for multiple unique configurations. For more information about how HTTP transport works, please see the [Model Context Protocol documentation on Transports](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports). The SonarQube MCP Server supports three transport modes: 1. [#stdio](#stdio "mention") is the default mode. This is the default mode, designed for single-user setups using command line tools or MCP clients. 2. [#http](#http "mention") is an unencrypted transport mode that can enable multiple client connections to a remote HTTP server. Each client provides its own user token. This transport mode is not recommended. Use [#stdio](#stdio "mention") for local development or [#https](#https "mention") for multi-user production deployments. 3. [#https](#https "mention") is also for multi-user production environments and uses a security protocol. This mode is the same as HTTP plus TLS encryption. The use of SSL certificates is required. ### Stdio Stdio is the default mode for local development and single-user set ups used by all MCP clients. It's also the mode used by the [Agentic Analysis](https://app.gitbook.com/s/B4UT2GNiZKjtxFtcFAL7/analyzing-source-code/agentic-analysis "mention") and [Context Augmentation](https://app.gitbook.com/s/B4UT2GNiZKjtxFtcFAL7/analyzing-source-code/context-augmentation "mention") services. The [#common-variables](https://docs.sonarsource.com/sonarqube-mcp-server/environment-variables#common-variables "mention") are required to initialize any transport mode you choose. {% hint style="info" %} Although the examples below use `docker`, any OCI-compatible container runtime works (for example, Podman, nerdctl, etc). Simply replace `docker` with commands specific to your preferred tool. {% endhint %} **Docker example** {% tabs %} {% tab title="SONARQUBE CLOUD" %} Use this code sample when using the container image to configure your MCP HTTP server for integrating with SonarQube Cloud. ```bash { "mcpServers": { "sonarqube": { "command": "docker", "args": ["run", "-i", "--rm", "--init", "--pull=always", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "mcp/sonarqube"], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_ORG": "" } } } } ``` {% hint style="success" %} SONARQUBE\_URL should be defined as `https://sonarqube.us` each time you use a SonarQube Cloud configuration (SONARQUBE\_TOKEN + SONARQUBE\_ORG) and want to connect to US instance. See the [#common-variables](https://docs.sonarsource.com/sonarqube-mcp-server/environment-variables#common-variables "mention") article which explains when to use these variables. {% endhint %} {% hint style="warning" %} *User tokens* are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if *project tokens*, *global tokens*, or *scoped organization tokens* are used during the setup process. {% endhint %} {% endtab %} {% tab title="SONARQUBE SERVER" %} Use this code sample when using Docker to configure your MCP server for integrating with SonarQube Server or SonarQube Community Build. ```bash { "mcpServers": { "sonarqube": { "command": "docker", "args": ["run", "-i", "--rm", "--init", "--pull=always", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "mcp/sonarqube"], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_URL": "" } } } } ``` {% hint style="warning" %} *User tokens* are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if *project tokens*, *global tokens*, or *scoped organization tokens* are used during the setup process. {% endhint %} {% endtab %} {% endtabs %} ### HTTP {% hint style="danger" %} The HTTP [#transport-mode](#transport-mode "mention") is not recommended. Use [#stdio](#stdio "mention") for local development or [#https](#https "mention") for multi-user production deployments. {% endhint %} Enable HTTP transport for unencrypted multi-user scenarios where more than one client will connect to a shared server. The [#common-variables](https://docs.sonarsource.com/sonarqube-mcp-server/environment-variables#common-variables "mention") are required for initialization, in addition to the listed [#http-variables](https://docs.sonarsource.com/sonarqube-mcp-server/environment-variables#http-variables "mention") that clients will need to access the server. Once set up, each client must provide its own user token for access. ### HTTPS HTTPS configurations are very similar to [#http](#http "mention") but require SSL certificates. * For local development, use HTTP instead of HTTPS to avoid [#ssl-certificate](https://docs.sonarsource.com/sonarqube-mcp-server/environment-variables#ssl-certificate "mention") issues. * For production deployments with proper SSL certificates from a trusted CA, use HTTPS. **Docker example** {% tabs %} {% tab title="SONARQUBE CLOUD" %} Use this code sample when using the container image to configure your MCP HTTPS server for integrating with SonarQube Cloud. The server uses the `SONARQUBE_TOKEN` environment variable for initialization. Clients connect to the server using the `Authorization: Bearer` header. {% hint style="info" %} Although the examples below use `docker`, any OCI-compatible container runtime works (for example, Podman, nerdctl, etc). Simply replace `docker` with commands specific to your preferred tool. {% endhint %} ```bash # Start server (requires token for initialization) docker run --init --pull=always -p 8443:8443 \ -v $(pwd)/keystore.p12:/etc/ssl/mcp/keystore.p12:ro \ -e SONARQUBE_TRANSPORT=https \ -e SONARQUBE_HTTP_HOST=0.0.0.0 \ -e SONARQUBE_HTTP_PORT=8443 \ -e SONARQUBE_TOKEN="" \ -e SONARQUBE_ORG="" \ mcp/sonarqube ``` {% hint style="success" %} SONARQUBE\_URL should be defined as `https://sonarqube.us` each time you use a SonarQube Cloud configuration (SONARQUBE\_TOKEN + SONARQUBE\_ORG) and want to connect to US instance. See the [#common-variables](https://docs.sonarsource.com/sonarqube-mcp-server/environment-variables#common-variables "mention") article which explains when to use these variables. {% endhint %} {% hint style="warning" %} *User tokens* are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if *project tokens*, *global tokens*, or *scoped organization tokens* are used during the setup process. {% endhint %} {% endtab %} {% tab title="SONARQUBE SERVER" %} Use this code sample when using the container image to configure your MCP HTTP server for integrating with SonarQube Server or SonarQube Community Build. The server uses the `SONARQUBE_TOKEN` environment variable for initialization. Clients connect to the server using the `Authorization: Bearer` header. {% hint style="info" %} Although the examples below use `docker`, any OCI-compatible container runtime works (for example, Podman, nerdctl, etc). Simply replace `docker` with commands specific to your preferred tool. {% endhint %} ```bash # Start server (requires token for initialization) docker run --init --pull=always -p 8443:8443 \ -v $(pwd)/keystore.p12:/etc/ssl/mcp/keystore.p12:ro \ -e SONARQUBE_TRANSPORT=https \ -e SONARQUBE_HTTP_HOST=0.0.0.0 \ -e SONARQUBE_HTTP_PORT=8443 \ -e SONARQUBE_TOKEN="" \ -e SONARQUBE_URL="" \ mcp/sonarqube ``` {% hint style="warning" %} *User tokens* are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if *project tokens*, *global tokens*, or *scoped organization tokens* are used during the setup process. {% endhint %} {% endtab %} {% endtabs %} **Client configuration** {% hint style="warning" %} Deprecation notice: Passing the token via the `SONARQUBE_TOKEN` header is deprecated for HTTP(S) transport. * For HTTP(S) transport: use the `Authorization: Bearer ` header. This is mandatory for SonarQube Cloud embedded MCP, and recommended for all other HTTP(S) configurations. * For stdio transport: no change: `SONARQUBE_TOKEN` as an environment variable is unchanged. See [deprecations-and-removals](https://docs.sonarsource.com/sonarqube-mcp-server/deprecations-and-removals "mention") for details. {% endhint %} When connecting to the HTTP or HTTPS transport server, clients must include the `Authorization` header with a Bearer token in all requests. ```json { "mcpServers": { "sonarqube-https": { "url": "https://:8443/mcp", "headers": { "Authorization": "Bearer " } } } } ``` {% hint style="warning" %} *User tokens* are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if *project tokens*, *global tokens*, or *scoped organization tokens* are used during the setup process. {% endhint %} ## Custom certificates If your instance of SonarQube Server uses a self-signed certificate or a certificate from a private Certificate Authority (CA), you can add custom certificates to the container. ### Supported certificate formats The container supports the following certificate formats: * `.crt` files (PEM or DER encoded) * `.pem` files (PEM encoded) {% hint style="info" %} Although the examples below use `docker`, any OCI-compatible container runtime works (for example, Podman, nerdctl, etc). Simply replace `docker` with commands specific to your preferred tool. {% endhint %}
Using a Volume Mount Mount a directory containing your certificates when running the container: ```bash docker run -i --rm --init --pull=always \ -v /path/to/your/certificates/:/usr/local/share/ca-certificates/:ro \ -e SONARQUBE_TOKEN="" \ -e SONARQUBE_URL="" \ mcp/sonarqube ``` {% hint style="warning" %} *User tokens* are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if *project tokens*, *global tokens*, or *scoped organization tokens* are used during the setup process. {% endhint %}
Custom certificates When using custom certificates, you can modify your MCP configuration to mount the certificates. Here an example when connecting to SonarQube Server or SonarQube Community Build: ```json { "sonarqube": { "command": "docker", "args": [ "run", "-i", "--rm", "--init", "--pull=always", "-v", "/path/to/your/certificates/:/usr/local/share/ca-certificates/:ro", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "mcp/sonarqube" ], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_URL": "" } } } ``` {% hint style="warning" %} *User tokens* are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if *project tokens*, *global tokens*, or *scoped organization tokens* are used during the setup process. {% endhint %}
## Proxy The SonarQube MCP Server supports HTTP proxies through standard Java proxy system properties.
Configure proxy settings You can configure proxy settings using Java system properties. These can be set as environment variables or passed as JVM arguments. **Common proxy properties** | Property | Description | Example | | -------------------- | -------------------------------------------- | -------------------------------------- | | `http.proxyHost` | HTTP proxy hostname | `proxy.example.com` | | `http.proxyPort` | HTTP proxy port | `8080` | | `https.proxyHost` | HTTPS proxy hostname | `proxy.example.com` | | `https.proxyPort` | HTTPS proxy port | `8443` | | `http.nonProxyHosts` | Hosts that bypass the proxy (pipe-separated) | `localhost\|127.0.0.1\|*.internal.com` | **Proxy authentication** If your proxy requires authentication, the SonarQube MCP Server uses Java's standard authentication mechanism. You can set up proxy credentials using Java system properties: | Property | Description | Example | | --------------------- | -------------------- | -------------- | | `http.proxyPassword` | HTTP proxy password | `yourpassword` | | `http.proxyUser` | HTTP proxy username | `yourusername` | | `https.proxyPassword` | HTTPS proxy password | `yourpassword` | | `https.proxyUser` | HTTPS proxy username | `yourusername` |