For the complete documentation index, see llms.txt. This page is also available as Markdown.

Environment variables

Environment variables reference for the SonarQube MCP Server.

The environment variables you need depend on your Sonar product and deployment type. Variables are grouped into four main categories based on your environment.

Common variables

Common variables configure how the server connects and authenticates. Requirements differ by transport mode; see each variable for details.

SONARQUBE_ORG

For SonarQube Cloud only. Optional organization key. When set, it fixes the Cloud organization.

In stdio mode, a token without SONARQUBE_URL connects to SonarQube Cloud (https://sonarcloud.io). Set SONARQUBE_ORG to fix one organization for the process. Organization-aware tools then omit the organization argument, and a call that passes it is rejected. This works the same way as projectKey when SONARQUBE_PROJECT_KEY is set.

Leave SONARQUBE_ORG unset to choose an organization on each tool call. If your token belongs to exactly one organization, the server selects it at startup and keeps it as the default. Zero or multiple organizations leave the organization unresolved. Call list_organizations, then pass a returned key as organization. That argument applies only to the call and does not change the detected default.

In Streamable HTTP mode, setting SONARQUBE_ORG on the SonarQube MCP Server is deprecated for token requests. If you still set it, the SonarQube MCP Server logs a warning at startup, fixes the organization for every token request, and rejects a client SONARQUBE_ORG header and a tool organization argument. When you do not set it on the SonarQube MCP Server, an optional client SONARQUBE_ORG header fixes the organization for that token request and rejects the tool argument. Without the header, pass organization on the tool call. See Self-hosted setups and Deprecations and removals.

On the SonarQube Cloud-hosted MCP server, an OAuth request rejects a SONARQUBE_ORG header. Call list_organizations, then pass organization on the tool. Self-hosted deployments continue to use SonarQube tokens.

SONARQUBE_TOKEN

Your SonarQube Cloud token (see Managing Personal Access Tokens) or your SonarQube Server token (see Managing your tokens).

In stdio mode, set SONARQUBE_TOKEN as an environment variable. The server needs it at startup and fails without it. In Streamable HTTP mode, the startup token is optional. Each client sends its own token in the Authorization: Bearer <YourSonarQubeUserToken> header with every request. To enable analyze_code_snippet over HTTP or HTTPS, set a startup SONARQUBE_TOKEN. The analysis toolset is enabled by default; if you set SONARQUBE_TOOLSETS, include analysis. The startup token initializes the analyzers. On SonarQube Cloud, analyzer downloads are anonymous, and analysis calls use the caller's token and the organization selected for the request to retrieve quality profiles and active rules. Without a startup token, snippet analysis and analyzer downloads are unavailable, even with SONARQUBE_FORCE_LOCAL_ANALYSIS=true.

Deprecation notice (Streamable HTTP transport): For SonarQube tokens, passing the token via a SONARQUBE_TOKEN HTTP header is deprecated. Use the Authorization: Bearer <YourSonarQubeUserToken> header instead. The SonarQube Cloud-hosted MCP server also accepts OAuth sign-in. For stdio transport, SONARQUBE_TOKEN as an environment variable is unchanged. See HTTPS for details.

SONARQUBE_URL

  • SonarQube Server or SonarQube Community Build: Set to your Server base URL.

  • SonarQube Cloud, US region: Set to https://sonarqube.us.

  • SonarQube Cloud, EU region: Not required. The default is https://sonarcloud.io. A token without SONARQUBE_URL connects to SonarQube Cloud.

Use SonarQube Server 2025.1 or newer, or SonarQube Community Build 25.1 or newer. The server checks the version at startup. See Prerequisites.

Base variables

Base variables are used when building and running the MCP server locally. The server needs to know how to identify the client and where the local storage location can be found. These variables may or may not be required depending on your configuration. For example, if you're running the container image:

Environment variable
Description

SONARQUBE_DEBUG_ENABLED

When set to true, enables debug logging. Debug logs are written to both the log file and STDERR. Default: false. Use this variable to troubleshoot connectivity or configuration issues.

SONARQUBE_IDE_PORT

Optional port number between 64120 and 64130 used to connect SonarQube MCP Server with SonarQube for IDE.

SONARQUBE_FORCE_LOCAL_ANALYSIS

Set to true to use analyze_code_snippet instead of Vortex analysis on SonarQube Cloud stdio. Default: false. See SONARQUBE_FORCE_LOCAL_ANALYSIS.

SONARQUBE_LOG_TO_FILE_DISABLED

When set to true, disables writing logs to disk. No log files are created under STORAGE_PATH/logs/. Default: false. Typical use case: containerized or ephemeral environments where log files on disk are not needed.

STORAGE_PATH

An absolute path to a writable directory where SonarQube MCP Server will store its files (e.g., for creation, updates, and persistence). This path is automatically provided when using the container image.

SONARQUBE_PROJECT_KEY

Optional default project key used by all tools that require a project key. When set, the projectKey parameter is removed from the schemas of relevant tools. Typical use case: working on a single project.

SONARQUBE_FORCE_LOCAL_ANALYSIS

Set this to true to register analyze_code_snippet instead of run_advanced_code_analysis on SonarQube Cloud stdio. This includes organizations with an active Vortex subscription, and it applies when SonarQube for IDE is connected. Enable the analysis toolset, then restart the server. Default: false.

This setting has no effect on SonarQube Server or on SonarQube Cloud over HTTP or HTTPS.

HTTP variables

HTTP variables are used when multiple clients connect to a shared MCP server over Streamable HTTP. Each client provides its own user token.

Environment variable
Description
Default

SONARQUBE_TRANSPORT

Set to http to enable Streamable HTTP transport

not defined (stdio)

SONARQUBE_HTTP_HOST

Host to bind (defaults to localhost for security)

127.0.0.1

SONARQUBE_HTTP_PORT

Port number (1024-65535), or 0 for an OS-assigned port

8080

SONARQUBE_HTTP_ALLOWED_ORIGINS

Comma-separated browser origins allowed for CORS (for example, https://my-app.example.com)

not defined

SONARQUBE_MCP_IN_CONTAINER

Set to true in custom container images to suppress the startup warning when binding to 0.0.0.0. Already set in the official image.

false

If needed, information about HTTP and HTTPS proxy settings is available on the Environment considerations page.

HTTPS variables

HTTPS variables are the same as #http-variables but with TLS encryption for Streamable HTTP. HTTPS variables require an #ssl-certificate however, redefining the keystore parameter default values is optional.

Environment variable
Description
Default

SONARQUBE_TRANSPORT

Set to https to enable Streamable HTTP transport over TLS

not defined (stdio)

SONARQUBE_HTTP_HOST

Host to bind. Use 127.0.0.1 for localhost. Use 0.0.0.0 for the container image.

127.0.0.1

SONARQUBE_HTTP_PORT

Port number (typically 8443 for HTTPS), or 0 for an OS-assigned port

8080

SONARQUBE_HTTP_ALLOWED_ORIGINS

Comma-separated browser origins allowed for CORS (for example, https://my-app.example.com)

not defined

SONARQUBE_MCP_IN_CONTAINER

Set to true in custom container images to suppress the startup warning when binding to 0.0.0.0. Already set in the official image.

false

If needed, information about HTTP and HTTPS proxy settings is available on the Environment considerations page.

CORS policy

In Streamable HTTP mode (http or https), the server validates the browser Origin header as a browser-layer backstop on local bindings. Bearer token authentication remains the primary access control.

Origin enforcement (returns 403 when triggered):

  • Applies only on local bindings (127.0.0.1, localhost, 0.0.0.0)

  • Skipped when the request carries Authorization: Bearer … or the legacy SONARQUBE_TOKEN header (native MCP clients such as Cursor and Claude Desktop)

  • Skipped on OAuth discovery paths without a token: POST /mcp (401 discovery) and GET /.well-known/* (Protected Resource Metadata)

  • Not applied on remote host bindings (for example, SonarQube Cloud hosted); use SONARQUBE_HTTP_ALLOWED_ORIGINS for browser CORS only

Allowed origins (for CORS response headers and local enforcement):

  • When bound to 127.0.0.1 or localhost (default): localhost browser origins (http://localhost, http://127.0.0.1, http://[::1], with any port)

  • When bound to 0.0.0.0 (required for container port mapping): same CORS policy as localhost bindings

  • Use SONARQUBE_HTTP_ALLOWED_ORIGINS to add full origin URLs to the allowlist (for example, https://sonarcloud.io, https://my-app.example.com) when deploying behind a web application

SSL certificate

Environment variable
Description
Default

SONARQUBE_HTTPS_KEYSTORE_PASSWORD

Keystore password. Redefining the default value is optional.

sonarlint

SONARQUBE_HTTPS_KEYSTORE_PATH

Path to keystore file (.p12 or .jks). Redefining the default value is optional.

/etc/ssl/mcp/keystore.p12

SONARQUBE_HTTPS_KEYSTORE_TYPE

Keystore type (PKCS12 or JKS). Redefining the default value is optional.

PKCS12

See also the Custom certificates article for information about supported formats and using the container image with custom configurations of your certificate.

SOCKS5 proxy

SOCKS5 proxies are supported.

Property
Description
Default
Example

socksProxyHost

SOCKS5 proxy hostname

—

localhost

socksProxyPort

SOCKS5 proxy port

1080

1080

java.net.socks.username

SOCKS5 username (if auth required)

—

myuser

java.net.socks.password

SOCKS5 password (if auth required)

—

mypassword

Tool enablement

MCP clients load every enabled tool (its name, description, and input schema) into your agent's context on every conversation. Limit that list with SONARQUBE_TOOLSETS to cut context usage and the token cost of each session.

By default, only important toolsets are enabled. Enable additional toolsets only when you need them.

SONARQUBE_TOOLSETS

Comma-separated list of toolsets to enable. When defined, only the listed toolsets are available. If not defined, the following toolsets are enabled by default: analysis, ide, issues, projects, quality-gates, rules, duplications, measures, security-hotspots, dependency-risks, coverage, cag, agentic-readiness.

Note: The projects toolset is always enabled because it's required to find project keys for other operations. Vortex context tools (deprecated name: Context Augmentation/CAG) and Vortex analysis tools (deprecated name: Advanced Analysis/A3S) are only available in stdio mode and share a single combined subscription. The default toolsets include cag and analysis, which means a default stdio install loads the Vortex tools when your SonarQube Cloud organization or SonarQube Server has an active Vortex subscription, and the server then logs the deprecation warning described below. To avoid the warning, set SONARQUBE_TOOLSETS explicitly and include vortex along with every other toolset you need, because setting the variable replaces the defaults. Without a subscription, the Vortex tools do not load, and over Streamable HTTP they never load. On SonarQube Cloud, built-in run_advanced_code_analysis checks the organization selected for that call. Proxied context tools use the organization resolved at startup. Use the unified vortex toolset key. The deprecated cag and analysis keys still work on SonarQube Cloud and SonarQube Server 2026.5; a startup warning and a deprecation note in the server instructions are emitted when they are used without vortex. In Streamable HTTP mode, clients can send a SONARQUBE_TOOLSETS HTTP header to narrow this further per-request, but cannot enable toolsets beyond what the server was launched with. See Self-hosted setups for details.

Agentic Readiness tools are available only on SonarQube Cloud when the feature is enabled for your organization. In stdio mode, the server checks the feature flag at startup. In HTTP or HTTPS mode, the server does not load these tools unless you opt in explicitly. To opt in, set SONARQUBE_TOOLSETS on the server and include agentic-readiness along with every other toolset you need, because setting the variable replaces the defaults.

SONARQUBE_READ_ONLY

When set to true, enables read-only mode and disables all write operations (for example, changing issue status). This filter is cumulative with SONARQUBE_TOOLSETS if both are defined. Default: false. In Streamable HTTP mode, clients can send a SONARQUBE_READ_ONLY HTTP header to further restrict individual requests to read-only, but cannot lift a server-level read-only restriction. See Self-hosted setups for details.

Available toolsets

Toolset
Key
Description

Analysis

analysis

Code analysis tools (local analysis via analyze_code_snippet, deprecated in favor of analyze_file_list/Vortex analysis)

IDE

ide

SonarQube for IDE bridge tools (file analysis, automatic analysis toggle); currently also included in analysis.

Coverage

coverage

Test coverage analysis and improvement tools

Dependency Risks

dependency-risks

Analyze dependency risks and security issues (SCA)

Duplications

duplications

Find code duplications across projects

Issues

issues

Search and manage SonarQube issues

Languages

languages

List supported programming languages

Measures

measures

Retrieve metrics and measures (includes both measures and metrics tools)

Portfolios

portfolios

Manage portfolios and enterprises (SonarQube Cloud and Server)

Projects

projects

Browse and search SonarQube projects, and list SonarQube Cloud organizations

Quality Gates

quality-gates

Access quality gates and their status

Rules

rules

Browse and search SonarQube rules

Security Hotspots

security-hotspots

Search and review security hotspots

Sources

sources

Access source code and SCM information

System

system

System administration tools (SonarQube Server only)

Webhooks

webhooks

Manage webhooks

Vortex Context

cag

Vortex context tools — stdio only. Deprecated in favor of vortex (old name: Context Augmentation/CAG)

Vortex

vortex

Unified, recommended toolset surfacing both Vortex context and Vortex analysis tools under one name (stdio only); the connected SonarQube Cloud plan or SonarQube Server license must have an active subscription

Agentic Readiness

agentic-readiness

Agentic Readiness Assessment tools (SonarQube Cloud; stdio requires the organization feature flag, HTTP or HTTPS requires explicit server opt-in)

Architecture

architecture

Read current and intended architecture, project directives, and project findings; replace intended models; and create, update, or delete project directives (not enabled by default). SonarQube Cloud requires a Team or Enterprise plan. On SonarQube Server, these tools require version 2026.6 or later and Developer edition or higher; they are not available on older versions or SonarQube Community Build.

Toolset examples

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.

Warning: User tokens are required when setting up connected mode or your SonarQube MCP server with SonarQube (Server, Cloud). Your binding will not function properly if you use project tokens, global tokens, or scoped organization tokens during setup.

Note: Docker's MCP Hub publishes the mcp/sonarqube image on its own cadence, so it may occasionally lag behind the latest release. The examples below use sonarsource/sonarqube-mcp instead, which receives new releases first and supports versioned tags for stable pinning.

Enable analysis, issues, and quality gates toolsets (using Docker with SonarQube Cloud):

Note: The projects toolset is always enabled automatically, and you do not need to include it in SONARQUBE_TOOLSETS.

Note: SONARQUBE_URL should be defined as https://sonarqube.us each time you connect to a SonarQube Cloud organization in the US region. Without it, the server connects to the EU region. See the Connecting to SonarQube Cloud in the US region section for details.

Enable read-only mode (using Docker with SonarQube Cloud):

SonarQube Server-hosted MCP configuration

The following properties configure the MCP proxy on SonarQube Server. Set them in conf/sonar.properties.

System property (sonar property and ENVIRONMENT_VARIABLE)
Description

sonar.mcp.enabled SONAR_MCP_ENABLED

Enables or disables the MCP proxy. (default: true)

sonar.mcp.serverUrl SONAR_MCP_SERVERURL

The URL where the MCP server will be running.

sonar.mcp.healthCheckInterval SONAR_MCP_HEALTHCHECKINTERVAL

Health check interval. (default: 30s) (optional)

Last updated

Was this helpful?