# Codex CLI

[Codex CLI](https://github.com/openai/codex) is OpenAI's terminal-based AI coding assistant. Use this setup when you want to use Sonar tools from within a Codex CLI workflow.

## Set up MCP for Codex CLI

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

In your `~/.codex/config.toml` file, add the following configuration:

{% 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 %}

{% 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="info" %}
This code sample configures the MCP server using [#stdio](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#stdio "mention") transport, where `SONARQUBE_TOKEN` is passed as an environment variable.

For [#http](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#http "mention"), [#https](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#https "mention"), or the [#mcp-server-in-sonarqube-cloud](https://docs.sonarsource.com/sonarqube-mcp-server/build-and-configure/configure#mcp-server-in-sonarqube-cloud "mention"), the `SONARQUBE_TOKEN` header is deprecated. Pass the token using the `"Authorization": "Bearer <YourSonarQubeUserToken>"` header instead.
{% endhint %}

**Codex CLI with SonarQube Cloud**

```toml
[mcp_servers.sonarqube]
command = "docker"
args = ["run", "--rm", "-i", "--init", "--pull=always", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "mcp/sonarqube"]
env = { "SONARQUBE_TOKEN" = "<YourSonarQubeUserToken>", "SONARQUBE_ORG" = "<YourOrganizationName>" }
```

**Codex CLI with SonarQube Server**

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

#### HTTPS

Use HTTPS when connecting Codex CLI 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 `~/.codex/config.toml` file:

```toml
[mcp_servers.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 `~/.codex/config.toml` file:

```toml
[mcp_servers.sonarqube]
url = "http://<YourSonarQubeMCPServer>:8080/mcp"
headers = { "Authorization" = "Bearer <YourSonarQubeUserToken>" }
```

## 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 Codex CLI

Once connected, Codex CLI can call SonarQube MCP tools on your behalf. See the [tools](https://docs.sonarsource.com/sonarqube-mcp-server/using/tools "mention") page for the full list of available tools.

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