Configure your MCP server

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

No matter if you're looking for a configuration for single-users (Stdio), secure multi-client (HTTPS), or unencrypted multi-user (HTTP) configurations, the SonarQube MCP Server has you covered. On this page, you'll find container image examples for setup with SonarQube Cloud and SonarQube Server, including requirements for user tokens and handling of custom certificates and proxies.

If you're unable to use a container image to deploy your MCP server, please see the Build your MCP Server page for alternatives.

Overview

The SonarQube MCP Server uses Stdio as its recommended and default mode when running a local configuration. This configuration is designed for single-user access however, it's possible to manage your MCP server using a Transport mode configuration, designed for shared access across a network using HTTPS or HTTP connection protocols.

Connecting to SonarQube Cloud in the US region

Connecting your SonarQube MCP Server with your SonarQube Cloud US instance requires the use of 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 and CLI quickstart guides will include an example to configure SONARQUBE_URL when connecting to a SonarQube Cloud organization in the US region.

For more detail about SonarQube Cloud accounts hosted in the US region, see the Getting started in the US region page.

MCP Server in SonarQube Cloud

Use the embedded SonarQube Cloud MCP server to avoid running and maintaining your own MCP infrastructure while always using the current server version. The embedded server exposes a smaller, fixed subset of tools; for the available toolsets and configuration details, check SonarQube Cloud's MCP Server in SonarQube Cloud page.

Agentic Analysis and Context Augmentation

When using SonarQube Cloud's Agentic Analysis and Context Augmentation services, your SONARQUBE_TOKEN will allow your local MCP server configured for Stdio mode to authenticate to the SonarQube Cloud API. See the SonarQube Cloud pages Agentic Analysis and Context Augmentation to get the correct configuration details.

Transport mode

Once configured, your MCP server is hosted on a local network and can handle connections from multiple users; all of your team's developers can access the same MCP server and reduces the need for multiple unique configurations. For more information about how HTTP transport works, please see the Model Context Protocol documentation on Transports.

The SonarQube MCP Server supports three transport modes:

1. Stdio is the default mode, designed for single-user setups using command line tools or MCP clients.

2. HTTPS is for multi-user production environments and uses TLS encryption. SSL certificates are required.

3. HTTP is an unencrypted transport mode. This transport mode is not recommended. Use Stdio for local development or HTTPS for multi-user production deployments.

Stdio

Stdio is the recommended and default mode for local development and single-user set ups used by all MCP clients. It's also the mode used by the Agentic Analysis and Context Augmentation services. The Common variables are required to initialize any transport mode you choose.

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.

Docker example

SONARQUBE CLOUD

Use this code sample when using the container image to configure your MCP HTTP server for integrating with SonarQube Cloud.

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "mcp/sonarqube"],
      "env": {
        "SONARQUBE_TOKEN": "<YourSonarQubeUserToken>",
        "SONARQUBE_ORG": "<YourSonarQubeOrganization>"
      }
    }
  }
}

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 US instance. See the Common variables article which explains when to use these variables.

User tokens are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if project tokens, global tokens, or scoped organization tokens are used during the setup process.

SONARQUBE SERVER

HTTPS

HTTPS configurations are very similar to HTTP but require SSL certificates.

• For local development, use HTTP instead of HTTPS to avoid SSL certificate issues.

• For production deployments with proper SSL certificates from a trusted CA, use HTTPS.

Docker example

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.

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.

# 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="<YourSonarQubeUserToken>" \
  -e SONARQUBE_ORG="<YourSonarQubeOrganization>" \
  mcp/sonarqube

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 US instance. See the Common variables article which explains when to use these variables.

User tokens are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if project tokens, global tokens, or scoped organization tokens are used during the setup process.

SONARQUBE SERVER

Client configuration

Deprecation notice: Passing the token via the SONARQUBE_TOKEN header is deprecated for HTTP(S) transport.

• For HTTP(S) transport: use the Authorization: Bearer <YourSonarQubeUserToken> header. This is mandatory for SonarQube Cloud embedded MCP, and recommended for all other HTTP(S) configurations.

• For stdio transport: no change: SONARQUBE_TOKEN as an environment variable is unchanged.

See Deprecations and removals for details.

When connecting to an HTTPS transport server, clients must include the Authorization header with a Bearer token in all requests.

{
  "mcpServers": {
    "sonarqube": {
      "url": "https://<YourSonarQubeMCPServer>:8443/mcp",
      "headers": {
        "Authorization": "Bearer <YourSonarQubeUserToken>"
      }
    }
  }
}

User tokens are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if project tokens, global tokens, or scoped organization tokens are used during the setup process.

HTTP

The HTTP Transport mode is not recommended. Use Stdio for local development or HTTPS for multi-user production deployments.

Enable HTTP transport for unencrypted multi-user scenarios where more than one client will connect to a shared server. The Common variables are required for initialization, in addition to the listed HTTP variables that clients will need to access the server.

Once set up, each client must provide its own user token for access.

Client configuration

When connecting to an HTTP transport server, clients must include the Authorization header with a Bearer token in all requests.

{
  "mcpServers": {
    "sonarqube": {
      "url": "http://<YourSonarQubeMCPServer>:8080/mcp",
      "headers": {
        "Authorization": "Bearer <YourSonarQubeUserToken>"
      }
    }
  }
}

Service Endpoints

When running in HTTPS or HTTP transport mode, the server exposes a few unauthenticated service endpoints in addition to the MCP endpoint at /mcp. These are intended for service-to-service use (monitoring, orchestration, client compatibility checks) and do not 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.

Custom certificates

If your instance of SonarQube Server uses a self-signed certificate or a certificate from a private Certificate Authority (CA), you can add custom certificates to the container.

Supported certificate formats

The container supports the following certificate formats:

• .crt files (PEM or DER encoded)

• .pem files (PEM encoded)

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.

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>" \
  mcp/sonarqube

User tokens are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if project tokens, global tokens, or scoped organization tokens are used during the setup process.

Custom certificates

When using custom certificates, you can modify your MCP configuration to mount the certificates. Here an example when connecting 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",
      "mcp/sonarqube"
    ],
    "env": {
      "SONARQUBE_TOKEN": "<YourSonarQubeUserToken>",
      "SONARQUBE_URL": "<YourSonarQubeServerURL>"
    }
  }
}

User tokens are required when setting up connected mode or an MCP Server between SonarQube (Server, Cloud) and SonarQube for IDE. Note that the binding will not function properly if project tokens, global tokens, or scoped organization tokens are used during the setup process.

Proxy

The SonarQube MCP Server supports HTTP proxies through standard Java proxy system properties.

Configure proxy settings

You can 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. You can 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