# Windsurf

[Windsurf](https://windsurf.com/) is an agentic IDE from Codeium. Use this MCP server setup when you want Sonar tools available within the Cascade AI agent in Windsurf.

Windsurf lists the SonarQube MCP Server as a [security-focused extension](https://docs.windsurf.com/windsurf/recommended-plugins#security).

If you prefer using a centrally managed MCP server, see the [#mcp-server-in-sonarqube-cloud](#mcp-server-in-sonarqube-cloud "mention") article below.

## Set up MCP for Windsurf

### Environment variables

The following [#common-variables](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/environment-variables#common-variables "mention") are required. Note that `SONARQUBE_TOKEN` applies to stdio transport only. For HTTP, HTTPS, or the embedded SonarQube Cloud MCP server, use the `Authorization: Bearer <YourSonarQubeUserToken>` header instead.

* `SONARQUBE_TOKEN`: Your SonarQube user token (stdio transport).
* `SONARQUBE_ORG`: Your SonarQube Cloud organization key. Required for SonarQube Cloud only.
* `SONARQUBE_URL`: Your SonarQube Server or Community Build URL. Also required for SonarQube Cloud in the US region (`https://sonarqube.us`). Not needed for SonarQube Cloud in the EU region.

{% hint style="danger" %}
Your SonarQube token is a sensitive credential. Use environment variables to pass tokens rather than hardcoding them in configuration files. Never commit tokens to version control.
{% endhint %}

### Transport options

The SonarQube MCP Server supports three transport modes. Use [#stdio](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#stdio "mention") for local development and most use cases, [#https](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#https "mention") for production and team deployments, and [#http](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#http "mention") only on trusted internal networks.

#### Stdio (recommended)

Use [#stdio](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#stdio "mention") for local development or when you are the only user. It is also the transport used by [Agentic Analysis and Context Augmentation](#agentic-analysis-and-context-augmentation).

**Automatic MCP configuration**

When you're using an AI-enabled IDE such as Cursor, Windsurf, or VS Code with Copilot enabled, and have already completed your [Connected mode setup](https://app.gitbook.com/s/6LPRABg3ubAJhpfR5K0Y/connect-your-ide/setup "mention") in SonarQube for IDE with SonarQube Server or SonarQube Cloud, a quick select button is available.

* Select the <picture><source srcset="broken-reference" media="(prefers-color-scheme: dark)"><img src="broken-reference" alt="" data-size="line"></picture> icon, **Configure MCP Server** from the **CONNECTED MODE** view window to use your connected mode credentials to start using the SonarQube MCP Server. The same workflow is available in the **AI AGENTS CONFIGURATION** view.

If you've connected to a SonarQube Cloud organization in the US region, the configuration details will be shared.

Check out our YouTube demo to watch the Windsurf & SonarQube MCP Server integration in action.

{% embed url="<https://www.youtube.com/watch?v=bJoXEkwlBLc>" %}

{% hint style="info" %}
Windsurf subscribers on Team & Enterprise plans should add the SonarQube MCP Server to the list of allowed servers. See the Windsurf documentation about [Admin Controls](https://docs.windsurf.com/plugins/cascade/mcp#admin-controls-teams-&-enterprises).
{% endhint %}

**Manual configuration**

The SonarQube MCP Server is available in the Windsurf MCP Marketplace for the [Cascade MCP client](https://docs.windsurf.com/windsurf/cascade/mcp). Follow these instructions:

1. Open Windsurf **Settings** > **Cascade** > **MCP Servers** and select **Open MCP Marketplace**.
2. Search for `sonarqube` on the Cascade MCP Marketplace.
3. Choose the **SonarQube MCP Server** and select **Install**.
4. Add the required SonarQube user token. Then add an organization key if you want to connect with SonarQube Cloud, or the SonarQube URL if you want to connect to SonarQube Server or SonarQube Community Build.

{% hint style="success" %}
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](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/environment-variables#common-variables "mention") article which explains when to use these variables.
{% endhint %}

{% hint style="warning" %}
*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.
{% endhint %}

#### HTTPS

Use HTTPS when connecting Windsurf to a shared MCP server deployed for a team. This requires an [HTTPS transport server](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#https) to be running and accessible.

Add the following to your Windsurf MCP configuration file:

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

#### HTTP

{% hint style="danger" %}
The HTTP [#transport-mode](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#transport-mode "mention") is not recommended. Use [#stdio](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#stdio "mention") for local development or [#https](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#https "mention") for multi-user production deployments.
{% endhint %}

Use HTTP only on a trusted internal network or for local testing. This requires an [HTTP transport server](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#http) to be running.

Add the following to your Windsurf MCP configuration file:

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

## 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 #MCP Server in SonarQube Cloud](https://app.gitbook.com/s/B4UT2GNiZKjtxFtcFAL7/ai-capabilities/sonarqube-mcp-server#mcp-server-in-sonarqube-cloud "mention") 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](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#stdio "mention") mode to authenticate to the SonarQube Cloud API. See the SonarQube Cloud pages [Agentic Analysis](https://app.gitbook.com/s/B4UT2GNiZKjtxFtcFAL7/analyzing-source-code/agentic-analysis "mention") and [Context Augmentation](https://app.gitbook.com/s/B4UT2GNiZKjtxFtcFAL7/analyzing-source-code/context-augmentation "mention") to get the correct configuration details.

## Use Sonar tools from Windsurf

Once connected, you can use the tools provided by the SonarQube MCP Server in the Windsurf agent mode. See the [tools](https://docs.sonarsource.com/sonarqube-mcp-server/using/tools "mention") page for the full list of available tools.

See also the [Windsurf documentation](https://docs.windsurf.com/context-awareness/windsurf-overview#chat-specific-context-features) for information on adding explicit context.

{% hint style="info" %}
Concrete workflow examples for this IDE will be added after engineering review.
{% endhint %}