Environment considerations

This page outlines the various setups and transport modes available when running the SonarQube MCP Server, which allows its integration with a variety of clients.

The SonarQube MCP Server supports several setup options. Choose the one that best suits your workflow, then head to the IDE/CLI quickstart guides 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. It's also available on the GitHub MCP Registry.

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.

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.

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 <token>.
• 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.

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. See the #common-variables table for details about the parameter.

Where possible, each of the code samples given in the IDE/CLI quickstart guides 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 and context augmentation features, your SONARQUBE_TOKEN will allow your local MCP server configured for stdio mode to authenticate to the SonarQube Cloud API.

Run from JAR or build from source

To run the server without Docker, download a pre-built JAR from the SonarSource binaries repository. You can also build from source using JDK 21+ and Gradle. See Build 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:

docker run -i --rm --init --pull=always  \
  -v /path/to/your/certificates/:/usr/local/share/ca-certificates/:ro \
  -e SONARQUBE_TOKEN="<YourSonarQubeUserToken>" \
  -e SONARQUBE_URL="<YourSonarQubeURL>" \
  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:

{
  "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": "<YourSonarQubeUserToken>",
      "SONARQUBE_URL": "<YourSonarQubeServerURL>"
    }
  }
}

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 page to get in touch with us, or review the Troubleshooting page for common issues.