# Configure your MCP server No matter if you're looking for a configuration for single-users ([#stdio](#stdio "mention")), secure multi-client ([#https](#https "mention")), or unencrypted multi-user ([#http](#http "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") as its recommended and default mode 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 [#https](#https "mention") or [#http](#http "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 [IDE and CLI quickstart guides](https://docs.sonarsource.com/sonarqube-mcp-server/quickstart-guide#set-up-in-your-ide) will include an example to configure SONARQUBE\_URL when connecting to a SonarQube Cloud organization in the US region. For more detail 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 Use the embedded SonarQube Cloud MCP server 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; for the available toolsets and configuration details, check SonarQube Cloud's [MCP Server #MCP Server in SonarQube Cloud](https://app.gitbook.com/s/B4UT2GNiZKjtxFtcFAL7/ai-capabilities/sonarqube-mcp-server#mcp-server-in-sonarqube-cloud "mention") page. ## 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, designed for single-user setups using command line tools or MCP clients. 2. [#https](#https "mention") is for multi-user production environments and uses TLS encryption. SSL certificates are required. 3. [#http](#http "mention") is an unencrypted transport mode. This transport mode is not recommended. Use [#stdio](#stdio "mention") for local development or [#https](#https "mention") for multi-user production deployments. ### Stdio Stdio is the recommended and 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 %} ### 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 HTTPS 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 an HTTPS transport server, clients must include the `Authorization` header with a Bearer token in all requests. ```json { "mcpServers": { "sonarqube": { "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 %} ### 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. **Client configuration** When connecting to an HTTP transport server, clients must include the `Authorization` header with a Bearer token in all requests. ```json { "mcpServers": { "sonarqube": { "url": "http://:8080/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ### **Service Endpoints** When running in **HTTPS** or **HTTP** transport mode, the server exposes a few unauthenticated service endpoints in addition to the MCP endpoint at `/mcp`. These are intended for service-to-service use (monitoring, orchestration, client compatibility checks) and do not require an `Authorization` header. | Endpoint | Method | Description | Example response | | --------- | ------ | ------------------------------------------------------------------------------------------ | ---------------------- | | `/health` | `GET` | Liveness probe. Returns `200 OK` with an empty body once the server is accepting requests. | *(empty body)* | | `/info` | `GET` | Returns the MCP server version as JSON. Useful for verifying the deployed server version. | `{"version":"1.16.0"}` | These endpoints are not available when running with the **Stdio** transport. ## 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` |
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.