Self-hosted

This page provides information on self-hosted SonarQube MCP Server setups and the associated transport modes Stdio and Streamable HTTP (HTTP and HTTPS) including examples for each deployment.

The MCP specification defines two transport mechanisms: Stdio and Streamable HTTP. The SonarQube MCP Server supports both. When you enable Streamable HTTP, you can use unencrypted HTTP or TLS-encrypted HTTPS. See Stdio for the default local setup. Each mode includes a deployment example for configuring your client. See Environment variables 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 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 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 and context augmentation workflow. The 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 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.

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", "sonarsource/sonarqube-mcp"],
      "env": {
        "SONARQUBE_TOKEN": "<YourSonarQubeUserToken>",
        "SONARQUBE_ORG": "<YourSonarQubeOrganization>"
      }
    }
  }
}

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

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

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). Unencrypted 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) 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

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

# 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>" \
  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 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.

# 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_URL="<YourSonarQubeURL>" \
  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 <YourSonarQubeUserToken> 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 for details.

In Streamable HTTP mode (HTTP or HTTPS), the server is stateless: each client request must include an Authorization: Bearer <token> 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.

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

HTTP (Streamable HTTP)

Important: Unencrypted Streamable HTTP is not recommended. Use Stdio for local development or 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 are required for initialization, in addition to the listed 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.

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

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:

Identify your agent.
Find your common variables.
Enter the information into the SonarQube Server configuration generator and select the local (stdio) or remote server option.
Paste the generated configuration into your configuration file.

PreviousSonarQube Server-hosted NextPrompt examples

Last updated 19 days ago

Was this helpful?