> 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/environment-considerations.md). # Environment considerations The SonarQube MCP Server supports several setup options. Choose the one that best suits your workflow, then head to the [IDE/CLI quickstart guides](/sonarqube-mcp-server/setup/quickstart-guides.md) to get started. ## Hosting method When you self-host the SonarQube MCP Server, it runs from the official container image at [sonarsource/sonarqube-mcp on Docker Hub](https://hub.docker.com/r/sonarsource/sonarqube-mcp/tags). It's also available on the [GitHub MCP Registry](https://github.com/SonarSource/sonarqube-mcp-server). A SonarQube Cloud-hosted setup is also available. ### When to use the SonarQube Cloud-hosted MCP Server Use this setup when you want the fastest path to connect from a client. * No local or shared server deployment is required. * SonarQube Cloud manages the server version for you. * Clients connect directly to the hosted MCP endpoint. * You get a smaller, fixed subset of tools. For more information, see [SonarQube Cloud-hosted](/sonarqube-mcp-server/setup/sonarqube-cloud-hosted.md). ### When to use a local server Use this setup for local development and single-user workflows. * The server runs over the stdio transport mode. * The client starts the server as a local process. * Configuration and authentication use environment variables. * You get the full MCP tool set. * This is the recommended default for most IDE and CLI integrations. For more information, see [Self-hosted setups](/sonarqube-mcp-server/setup/self-hosted.md). ### When to use a remote server Use this setup for shared team access and centrally managed deployments. * The server runs over Streamable HTTP using `HTTPS` or `HTTP` transport modes. * Clients connect to `/mcp` and send `Authorization: Bearer `. * Use `HTTPS` for production deployments. * Use `HTTP` only in trusted, non-production environments. * Shared deployments also expose `/health` and `/info`. For more information, see [Self-hosted setups](/sonarqube-mcp-server/setup/self-hosted.md). ## Connecting to SonarQube Cloud in the US region Connecting your SonarQube MCP Server with your SonarQube Cloud US instance requires the use of a common variable, defined as `SONARQUBE_URL=https://sonarqube.us` in your configuration file. Review the MCP server's [Common variables](/sonarqube-mcp-server/reference/environment-variables.md#common-variables) for details about the parameter. Where possible, each of the code samples given in the [IDE/CLI quickstart guides](/sonarqube-mcp-server/setup/quickstart-guides.md) will include an example to configure `SONARQUBE_URL` when connecting to a SonarQube Cloud organization in the US region. ## Sonar Vortex: agentic analysis and context augmentation features When using Sonar Vortex's [agentic analysis](/agent-centric-development-cycle/verify/how-to-guides/make-your-agent-verify-its-code.md) and [context augmentation](/agent-centric-development-cycle/guide/add-context-to-generate-better-code.md) features, your `SONARQUBE_TOKEN` will allow your local MCP server configured for stdio mode to authenticate to the SonarQube Cloud API. ## SonarQube Cloud organization in stdio mode In stdio mode, you can omit `SONARQUBE_ORG` when your user token belongs to exactly one SonarQube Cloud organization. The server lists organizations at startup and selects the only one automatically. You still must set `SONARQUBE_ORG` or `SONARQUBE_URL` so the server connects to SonarQube Cloud rather than SonarQube Server. Set `SONARQUBE_ORG` explicitly when your token is associated with multiple organizations. Streamable HTTP mode does not auto-detect organizations at startup; each client supplies the organization per request. See [SONARQUBE\_ORG](/sonarqube-mcp-server/reference/environment-variables.md#sonarqube_org) and [Troubleshooting](/sonarqube-mcp-server/resources/troubleshooting.md) for details. ## Run from JAR or build from source To run the server without Docker, download a pre-built JAR from the [SonarSource binaries repository](https://binaries.sonarsource.com/?prefix=Distribution/sonarqube-mcp-server/). You can also build from source using JDK 21+ and Gradle. See [Build](/sonarqube-mcp-server/setup/build.md) for the complete details. ## Custom certificates If your instance of SonarQube Server uses a self-signed certificate or a certificate from a private Certificate Authority (CA), add custom certificates to the container. The container supports the following certificate formats: * `.crt` files (PEM or DER encoded) * `.pem` files (PEM encoded) > **Warning:** *User tokens* are required when setting up connected mode or your SonarQube MCP server with SonarQube (Server, Cloud). Your binding won't function properly if you use *project tokens*, *global tokens*, or *scoped organization tokens* during setup. ### 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="" \ sonarsource/sonarqube-mcp ``` ### Custom certificates (JSON config) When using custom certificates, modify your MCP configuration to mount them. The following example shows a connection 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", "sonarsource/sonarqube-mcp" ], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_URL": "" } } } ``` > **Note:** When you [run from JAR](/sonarqube-mcp-server/setup/build.md#run-from-jar) instead of the container, the volume mount above installs certificates into the container's OS trust store, which the server also reads. If you cannot use the OS trust store (notably on Windows, where it is not consulted), point the JVM at a Java truststore holding the CA certificate: `-Djavax.net.ssl.trustStore=/path/to/truststore.p12 -Djavax.net.ssl.trustStoreType=PKCS12 -Djavax.net.ssl.trustStorePassword=`. It is added on top of the default trusted certificates. ## Client certificate (mutual TLS) If your SonarQube Server requires clients to present a certificate during the TLS handshake (mutual TLS), provide a PKCS12 keystore by mounting it into the container and passing its location via `JAVA_OPTS`. ### Using a PKCS12 keystore Mount your `.p12` or `.pfx` file into the container and set the `JAVA_OPTS` environment variable with the keystore properties: ```bash docker run --init --pull=always -i --rm \ -v /path/to/client.p12:/etc/ssl/mcp/client.p12:ro \ -e JAVA_OPTS="-Djavax.net.ssl.keyStore=/etc/ssl/mcp/client.p12 -Djavax.net.ssl.keyStoreType=PKCS12 -Djavax.net.ssl.keyStorePassword=" \ -e SONARQUBE_TOKEN="" \ -e SONARQUBE_URL="" \ sonarsource/sonarqube-mcp ``` > **Note:** The certificate file must be readable by the container process. Check and fix permissions if needed: > > ```bash > ls -la /path/to/client.p12 # look for -rw-r--r-- (644) or wider > chmod 644 /path/to/client.p12 # grant read access to the container user > ``` Omit `-Djavax.net.ssl.keyStorePassword` if the keystore has no passphrase. The passphrase used here is visible through `docker inspect` or the process list. ### Using a PKCS12 keystore (JSON config) ```json { "sonarqube": { "command": "docker", "args": [ "run", "--init", "--pull=always", "-i", "--rm", "-v", "/path/to/client.p12:/etc/ssl/mcp/client.p12:ro", "-e", "JAVA_OPTS", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "sonarsource/sonarqube-mcp" ], "env": { "JAVA_OPTS": "-Djavax.net.ssl.keyStore=/etc/ssl/mcp/client.p12 -Djavax.net.ssl.keyStoreType=PKCS12 -Djavax.net.ssl.keyStorePassword=", "SONARQUBE_TOKEN": "", "SONARQUBE_URL": "" } } } ``` ### Using a PKCS12 keystore with a standalone JAR When you [run from JAR](/sonarqube-mcp-server/setup/build.md#run-from-jar), pass the keystore properties as JVM arguments before `-jar`: ```bash java \ -Djavax.net.ssl.keyStore=/path/to/client.p12 \ -Djavax.net.ssl.keyStoreType=PKCS12 \ -Djavax.net.ssl.keyStorePassword= \ -jar ``` Omit `-Djavax.net.ssl.keyStorePassword` if the keystore has no passphrase. ### Client certificate with a standalone JAR (JSON config) ```json { "sonarqube": { "command": "java", "args": [ "-Djavax.net.ssl.keyStore=/path/to/client.p12", "-Djavax.net.ssl.keyStoreType=PKCS12", "-Djavax.net.ssl.keyStorePassword=", "-jar", "" ], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_URL": "" } } } ``` > **Note:** PEM certificate and key files (separate `.crt`/`.key` files) must be converted to PKCS12 format first. Use `openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12` to convert them. ## Proxy The SonarQube MCP Server supports HTTP proxies through standard Java proxy system properties. ### Configure proxy settings 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. 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` | ## Need help? The environment options above cover most use cases. If you're having trouble with your configuration, visit the [Help](/sonarqube-mcp-server/resources/help.md) page to get in touch with us, or review the [Troubleshooting](/sonarqube-mcp-server/resources/troubleshooting.md) page for common issues. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sonarsource.com/sonarqube-mcp-server/setup/environment-considerations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.