> 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/self-hosted.md). # Self-hosted The [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) defines two transport mechanisms: Stdio and Streamable HTTP. The SonarQube MCP Server supports both. When you enable Streamable HTTP, you can use unencrypted [HTTP](#http-streamable-http) or TLS-encrypted [HTTPS](#https-streamable-http-over-tls). See [Stdio](#local-server-stdio) for the default local setup. Each mode includes a deployment example for configuring your client. See [Environment variables](/sonarqube-mcp-server/reference/environment-variables.md) for details about required configuration values. | MCP transport | Server mode | Typical use | | ------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Stdio** | Default (no `SONARQUBE_TRANSPORT`) | Local MCP clients that launch the server as a subprocess (Cursor, Claude Code, VS Code, etc.) | | **Streamable HTTP** | `SONARQUBE_TRANSPORT=http` or `https` | Remote or multi-user deployments; clients connect to `/mcp` over HTTP(S) (for example, Windsurf with a self-hosted server URL) | > **Note:** Streamable HTTP is the current MCP network transport. The older SSE-only HTTP transport from earlier MCP versions is deprecated and not supported. > **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. ## Local server (Stdio) For independent users who need a quick setup for their specific IDE or CLI. Run the [sonarsource/sonarqube-mcp](https://hub.docker.com/r/sonarsource/sonarqube-mcp/tags) container image using stdio transport for local development. Use `sonarsource/sonarqube-mcp` for automatic updates (with `--pull=always`), or pin to a version tag (for example, `sonarsource/sonarqube-mcp:1.18.1.2664`) for reproducible deployments. This gives access to the full tool set. The [mcp/sonarqube](https://hub.docker.com/r/mcp/sonarqube) image is also available on Docker's MCP Hub. The stdio transport mode is the recommended and default mode for local development and single-user setups used by most MCP clients. It's also the mode used in your [agentic analysis](/agent-centric-development-cycle/verify/sonar-vortex-agentic-analysis.md) and [context augmentation](/agent-centric-development-cycle/guide/sonar-vortex-context-augmentation.md) workflow. The [common variables](/sonarqube-mcp-server/reference/environment-variables.md#common-variables) are required to initialize any transport mode you choose. **Docker example** > **Note:** 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. > **Note:** Docker's MCP Hub publishes the [`mcp/sonarqube`](https://hub.docker.com/r/mcp/sonarqube) image on its own cadence, so it may occasionally lag behind the latest release. The examples below use [`sonarsource/sonarqube-mcp`](https://hub.docker.com/r/sonarsource/sonarqube-mcp/tags) instead, which receives new releases first and supports versioned tags for stable pinning. ### SonarQube Cloud Use this code sample when using the container image to configure your MCP HTTP server for integrating with SonarQube Cloud. ```json { "mcpServers": { "sonarqube": { "command": "docker", "args": ["run", "-i", "--rm", "--init", "--pull=always", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "sonarsource/sonarqube-mcp"], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_ORG": "" } } } } ``` > **Tip:** In stdio mode, `SONARQUBE_ORG` is optional when your user token belongs to exactly one SonarQube Cloud organization. The server auto-detects it at startup. Set `SONARQUBE_ORG` explicitly when your token has access to multiple organizations. See [SONARQUBE\_ORG](/sonarqube-mcp-server/reference/environment-variables.md#sonarqube_org) for details. > **Note:** 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 a US-region instance. See the [Connecting to SonarQube Cloud in the US region](/sonarqube-mcp-server/setup/environment-considerations.md#connecting-to-sonarqube-cloud-in-the-us-region) section for details. ### SonarQube Server Use this code sample when using Docker to configure your MCP server for integrating with SonarQube Server or SonarQube Community Build. ```json { "mcpServers": { "sonarqube": { "command": "docker", "args": ["run", "-i", "--rm", "--init", "--pull=always", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "sonarsource/sonarqube-mcp"], "env": { "SONARQUBE_TOKEN": "", "SONARQUBE_URL": "" } } } } ``` ## Remote server (Streamable HTTP) This setup is suited for a central server that multiple users will access, using their own clients. Clients connect over Streamable HTTP, the MCP network transport for remote servers. For production, use [HTTPS (Streamable HTTP over TLS)](#https-streamable-http-over-tls). Unencrypted [HTTP (Streamable HTTP)](#http-streamable-http) is supported only in trusted, non-production environments. ### HTTPS (Streamable HTTP over TLS) HTTPS configurations are very similar to [HTTP (Streamable HTTP)](#http-streamable-http) but require SSL certificates. * For local development, use HTTP instead of HTTPS to avoid [SSL certificate](/sonarqube-mcp-server/reference/environment-variables.md#ssl-certificate) issues. * For production deployments with proper SSL certificates from a trusted CA, use HTTPS. **Docker example** > **Note:** 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. > **Note:** When running in a container, set `SONARQUBE_HTTP_HOST=0.0.0.0` so the container listens on all interfaces and the runtime's port mapping works. The host-side `-p` port flag controls who can reach the server from outside the container. `SONARQUBE_HTTP_HOST=0.0.0.0` only controls where the server listens inside the container, so browser CORS still allows localhost origins by default. To add more browser origins to your allowlist, set `SONARQUBE_HTTP_ALLOWED_ORIGINS`. See the [CORS policy](/sonarqube-mcp-server/reference/environment-variables.md#cors-policy) article for more details. #### 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. ```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="" \ sonarsource/sonarqube-mcp ``` > **Note:** 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 a US-region instance. See the [Connecting to SonarQube Cloud in the US region](/sonarqube-mcp-server/setup/environment-considerations.md#connecting-to-sonarqube-cloud-in-the-us-region) section for details. #### 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. ```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="" \ sonarsource/sonarqube-mcp ``` **Client configuration** > **Warning:** Deprecation notice: Passing the token via the `SONARQUBE_TOKEN` header is deprecated for Streamable HTTP transport. > > * For Streamable HTTP transport (HTTP or HTTPS): use the `Authorization: Bearer ` header. This is mandatory for SonarQube Cloud embedded MCP, and recommended for all other Streamable HTTP configurations. > * For stdio transport: no change: `SONARQUBE_TOKEN` as an environment variable is unchanged. > > See [common variables](/sonarqube-mcp-server/reference/environment-variables.md#common-variables) for details. In Streamable HTTP mode (HTTP or HTTPS), the server is stateless: each client request must include an `Authorization: Bearer ` header carrying the user's own SonarQube token. Clients can also narrow the visible tools per-request by supplying `SONARQUBE_TOOLSETS` and/or `SONARQUBE_READ_ONLY` headers; these apply additional filtering on top of the server-level configuration; they can only reduce the scope, never expand it. When connecting over HTTPS, clients must include the `Authorization` header with a Bearer token in all requests. ```json { "mcpServers": { "sonarqube": { "type": "https", "url": "https://:8443/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ### HTTP (Streamable HTTP) > **Important:** Unencrypted Streamable HTTP is not recommended. Use [Stdio](#local-server-stdio) for local development or [HTTPS (Streamable HTTP over TLS)](#https-streamable-http-over-tls) for multi-user production deployments. Enable unencrypted Streamable HTTP transport for multi-user scenarios where more than one client will connect to a shared server. The [common variables](/sonarqube-mcp-server/reference/environment-variables.md#common-variables) are required for initialization, in addition to the listed [HTTP variables](/sonarqube-mcp-server/reference/environment-variables.md#http-variables) that clients will need to access the server. After setup, each client must provide its own user token for access. **Client configuration** When connecting over unencrypted HTTP, clients must include the `Authorization` header with a Bearer token in all requests. ```json { "mcpServers": { "sonarqube": { "type": "http", "url": "http://:8080/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ### Service endpoints When running in Streamable HTTP mode (`http` or `https`), the server exposes a few unauthenticated service endpoints in addition to the MCP endpoint at `/mcp`. These endpoints are for service-to-service use (monitoring, orchestration, client compatibility checks) and don't 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. ## Using the configuration generator Use the official SonarQube MCP Server configuration generator to get a configuration snippet for your setup. To do this: 1. Identify your agent. 2. Find your [common variables](/sonarqube-mcp-server/reference/environment-variables.md#common-variables). 3. Enter the information into the [SonarQube Server configuration generator](https://mcp.sonarqube.com/config-generator.html) and select the local (stdio) or remote server option. 4. Paste the generated configuration into your configuration file. --- # 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/self-hosted.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.