# 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](/agent-centric-development-cycle/developer-tools/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 available on the [mcp/sonarqube Docker Hub page](https://hub.docker.com/r/mcp/sonarqube). It's also available on the [GitHub MCP Registry](https://github.com/mcp/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](/agent-centric-development-cycle/developer-tools/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](/agent-centric-development-cycle/developer-tools/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 `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](/agent-centric-development-cycle/developer-tools/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. See the [#common-variables](/agent-centric-development-cycle/developer-tools/mcp-server/reference/environment-variables.md#common-variables) table for details about the parameter.

Where possible, each of the code samples given in the [IDE/CLI quickstart guides](/agent-centric-development-cycle/developer-tools/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.

## Agentic analysis and context augmentation

When using [Agentic Analysis](/agent-centric-development-cycle/features/agentic-analysis.md) and [Context Augmentation](/agent-centric-development-cycle/features/context-augmentation.md) services, your `SONARQUBE_TOKEN` will allow your local MCP server configured for stdio mode to authenticate to the SonarQube Cloud API.

## Build from source

For custom deployments, build the server from scratch using JDK 21+ and Gradle, or use [the JAR file](https://binaries.sonarsource.com/?prefix=Distribution/sonarqube-mcp-server/) that we've made available. See [Build](/agent-centric-development-cycle/developer-tools/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 an MCP Server between SonarQube Server and SonarQube for IDE. Binding won't work 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="<YourSonarQubeUserToken>" \
  -e SONARQUBE_URL="<YourSonarQubeURL>" \
  mcp/sonarqube
```

### 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",
      "mcp/sonarqube"
    ],
    "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](/agent-centric-development-cycle/developer-tools/mcp-server/resources/help.md) page to get in touch with us, or review the [Troubleshooting](/agent-centric-development-cycle/developer-tools/mcp-server/resources/troubleshooting.md) page for common issues.


---

# 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/agent-centric-development-cycle/developer-tools/mcp-server/setup/environment-considerations.md?ask=<question>
```

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.