> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-mcp-server/setup/quickstart-guides/github-copilot-cloud-agent.md). # GitHub Copilot cloud agent Set up the SonarQube MCP Server with the GitHub Copilot cloud agent and start using Sonar tools in your CI/CD environment. The [GitHub Copilot cloud agent](https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent) is an autonomous AI agent that operates inside your GitHub repository and CI/CD environment. Use this MCP server setup when you want Sonar tools available to the cloud agent during pull request workflows and automated tasks. If you're setting up the SonarQube agent through GitHub agent apps, see [Set up the SonarQube agent through GitHub agent apps](/agent-centric-development-cycle/developer-tools/agent-plugins/agent-apps-for-github.md) instead. ## Choose your setup The SonarQube MCP Server lets an AI agent query your SonarQube projects. With it, the GitHub Copilot cloud agent can look up issues, quality gates, and coverage while it works. You can use a server that SonarQube hosts, run your own. Choose how to connect: | Option | Is best for | What you get | Who sets it up | | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | | [SonarQube Cloud-hosted](#connect-to-a-sonarqube-hosted-mcp-server) | SonarQube Cloud users | Nothing to install and a smaller, fixed subset of tools. No Sonar Vortex. | You connect | | [SonarQube Server-hosted](#connect-to-a-sonarqube-hosted-mcp-server) | SonarQube Server 2026.3 and later (Developer, Enterprise, and Data Center editions) | Nothing to install on your machine. No Sonar Vortex. | An administrator installs it, and then you connect | | [Self-hosted MCP server](#set-up-a-self-hosted-mcp-server) | Full control | The MCP server that you run yourself, with the Sonar Vortex analysis and context tools through the Stdio transport | You | The [configuration generator](https://mcp.sonarqube.com/config-generator.html) gives you a snippet to paste into the MCP configuration section of the Copilot Cloud agent settings in your GitHub repository. ## Connect to a SonarQube-hosted MCP server To avoid running and maintaining your own MCP infrastructure while always using the current server version, connect to a SonarQube-hosted MCP server: * SonarQube Cloud-hosted: for SonarQube Cloud users. The MCP server is embedded in SonarQube Cloud, so there's nothing to install, and it exposes a smaller, fixed subset of tools. To connect, see the [SonarQube Cloud-hosted](/sonarqube-mcp-server/setup/sonarqube-cloud-hosted.md) page. * SonarQube Server-hosted: for SonarQube Server users on Developer, Enterprise, and Data Center editions, version 2026.3 and newer. An administrator installs the MCP server extension on your instance, and then you [connect your AI agent](/sonarqube-mcp-server/setup/sonarqube-server-hosted.md#connect-your-ai-agent). To install the extension, see the [SonarQube Server-hosted](/sonarqube-mcp-server/setup/sonarqube-server-hosted.md#install-the-mcp-server) page. Neither the SonarQube Cloud-hosted nor the SonarQube Server-hosted option supports Sonar Vortex, which requires local filesystem access. Sonar Vortex is not installed by a plugin or the SonarQube CLI for the GitHub Copilot cloud agent. To use it, set up a self-hosted MCP server. See [Vortex with the MCP server](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/how-to-guides/install-vortex-with-mcp.md). To get the connection snippet for either option, use the [configuration generator](https://mcp.sonarqube.com/config-generator.html) and select the matching hosting method. ## Set up a self-hosted MCP server A self-hosted MCP server runs on your machine or in your own environment, and you manage it yourself. ### Before you start The cloud agent uses GitHub repository or organization secrets to supply environment variables to the MCP server. Only secrets with names prefixed with `COPILOT_MCP_` are available to your MCP configuration. To add the required secrets to your repository, navigate to **Settings** > **Secrets and variables** > **Agents** > **Secrets** > **New repository secret**. Create one secret per environment variable your MCP server needs. To make the secrets available across all repositories in your organization, add them at the organization's **Settings** > **Secrets and variables** > **Agents** > **Secrets** > **New organization secret** instead. For more details, see GitHub's documentation on [configuring secrets and variables for the Copilot cloud agent](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/configure-secrets-and-variables) and on [setting up a Copilot environment for Copilot cloud agent](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/extend-cloud-agent-with-mcp#setting-up-a-copilot-environment-for-copilot-cloud-agent). The following [common variables](/sonarqube-mcp-server/reference/environment-variables.md#common-variables) are required, stored as `COPILOT_MCP_`-prefixed secrets: * `SONARQUBE_TOKEN` (stored as `COPILOT_MCP_SONARQUBE_TOKEN`): Your SonarQube user token (stdio transport). * `SONARQUBE_ORG` (stored as `COPILOT_MCP_SONARQUBE_ORG`): Your SonarQube Cloud organization key. Required for SonarQube Cloud only. * `SONARQUBE_URL` (stored as `COPILOT_MCP_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. > **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. When using these features, your `SONARQUBE_TOKEN` lets your local MCP server configured for [Stdio](/sonarqube-mcp-server/setup/self-hosted.md#local-server-stdio) mode authenticate to the SonarQube Cloud API. See [Sonar Vortex analysis](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) and [Sonar Vortex context](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) for more information. ### Configure manually The SonarQube MCP Server supports three transport modes. Use [Stdio](/sonarqube-mcp-server/setup/self-hosted.md#local-server-stdio) for local development and most use cases, [HTTPS](/sonarqube-mcp-server/setup/self-hosted.md#https-streamable-http-over-tls) for production and team deployments, and [HTTP](/sonarqube-mcp-server/setup/self-hosted.md#http-streamable-http) only on trusted internal networks. Use the official [SonarQube MCP Server configuration generator](https://mcp.sonarqube.com/config-generator.html) to get a configuration code snippet for your setup: 1. Identify the target MCP Client. 2. Find your [#common-variables](/sonarqube-mcp-server/reference/environment-variables.md#common-variables). 3. Choose a [hosting method](/sonarqube-mcp-server/setup/environment-considerations.md#hosting-method). 4. Enter the information into the configuration generator. 5. Paste the generated configuration into your configuration file. To configure by hand instead, select a transport tab. {% tabs %} {% tab title="STDIO (RECOMMENDED)" %} Use [Stdio](/sonarqube-mcp-server/setup/self-hosted.md#local-server-stdio) when the cloud agent needs to spin up its own MCP server process within the CI/CD environment. It's also the transport mode used in your [Sonar Vortex analysis](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) and [Sonar Vortex context](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) workflows. In your GitHub repository, navigate to **Settings** > **Code, planning, and automation** > **Copilot** > **Cloud agent** and add the following configuration in the MCP configuration section: > **Note:** This code sample configures the MCP server using [Stdio](/sonarqube-mcp-server/setup/self-hosted.md#local-server-stdio) transport, where `SONARQUBE_TOKEN` is passed as an environment variable. > > For [HTTPS](/sonarqube-mcp-server/setup/self-hosted.md#https-streamable-http-over-tls), [HTTP](/sonarqube-mcp-server/setup/self-hosted.md#http-streamable-http), or the [SonarQube-hosted MCP server](#connect-to-a-sonarqube-hosted-mcp-server), the `SONARQUBE_TOKEN` header is deprecated. Pass the token using the `"Authorization": "Bearer "` header instead. > **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](/sonarqube-mcp-server/setup/environment-considerations.md#connecting-to-sonarqube-cloud-in-the-us-region) section for details. > **Note:** Docker's MCP Hub publishes the [`mcp/sonarqube`](https://hub.docker.com/r/mcp/sonarqube) image on its own cadence, so it may occasionally lag behind the latest release. The examples below use [`sonarsource/sonarqube-mcp`](https://hub.docker.com/r/sonarsource/sonarqube-mcp/tags) instead, which receives new releases first and supports versioned tags for stable pinning. **GitHub Copilot cloud agent with SonarQube Cloud** ```jsonc { "mcpServers": { "sonarqube": { "type": "local", "command": "docker", "args": [ "run", "--init", "--pull=always", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_ORG", "sonarsource/sonarqube-mcp" ], "env": { "SONARQUBE_TOKEN": "COPILOT_MCP_SONARQUBE_TOKEN", "SONARQUBE_ORG": "COPILOT_MCP_SONARQUBE_ORG", //"SONARQUBE_URL": "COPILOT_MCP_SONARQUBE_URL" }, "tools": ["*"] } } } ``` **GitHub Copilot cloud agent with SonarQube Server** ```json { "mcpServers": { "sonarqube": { "type": "local", "command": "docker", "args": [ "run", "--init", "--pull=always", "--rm", "-i", "-e", "SONARQUBE_TOKEN", "-e", "SONARQUBE_URL", "sonarsource/sonarqube-mcp" ], "env": { "SONARQUBE_TOKEN": "COPILOT_MCP_SONARQUBE_TOKEN", "SONARQUBE_URL": "COPILOT_MCP_SONARQUBE_URL" }, "tools": ["*"] } } } ``` > **Tip:** To verify the connection, ask your AI agent to call the SonarQube MCP `ping_system` tool. For example: *"Ping the SonarQube MCP server."* > **Note:** No restart is required. Each Copilot cloud agent task runs in a fresh environment and picks up your updated `COPILOT_MCP_*` secrets automatically. > {% endtab %} {% tab title="HTTPS" %} Use HTTPS when connecting the cloud agent to a shared MCP server deployed for a team. This requires an [HTTPS transport server](/sonarqube-mcp-server/setup/self-hosted.md#https-streamable-http-over-tls) to be running and accessible. In your GitHub repository, navigate to **Settings** > **Code, planning, and automation** > **Copilot** > **Cloud agent** and add the following configuration in the MCP configuration section: ```json { "mcpServers": { "sonarqube": { "type": "https", "url": "https://:8443/mcp", "headers": { "Authorization": "Bearer COPILOT_MCP_SONARQUBE_TOKEN" }, "tools": ["*"] } } } ``` > **Tip:** To verify the connection, ask your AI agent to call the SonarQube MCP `ping_system` tool. For example: *"Ping the SonarQube MCP server."* > **Note:** No restart is required. Each Copilot cloud agent task runs in a fresh environment and picks up your updated `COPILOT_MCP_*` secrets automatically. > {% endtab %} {% tab title="HTTP" %} > **Important:** The [HTTP](/sonarqube-mcp-server/setup/self-hosted.md#http-streamable-http) transport mode is not recommended. Use [Stdio](/sonarqube-mcp-server/setup/self-hosted.md#stdio) for local development or [HTTPS](/sonarqube-mcp-server/setup/self-hosted.md#https-streamable-http-over-tls) for multi-user production deployments. Use HTTP only on a trusted internal network or for local testing. This requires an [HTTP transport server](/sonarqube-mcp-server/setup/self-hosted.md#http-streamable-http) to be running. In your GitHub repository, navigate to **Settings** > **Code, planning, and automation** > **Copilot** > **Cloud agent** and add the following configuration in the MCP configuration section: ```json { "mcpServers": { "sonarqube": { "type": "http", "url": "http://:8080/mcp", "headers": { "Authorization": "Bearer COPILOT_MCP_SONARQUBE_TOKEN" }, "tools": ["*"] } } } ``` > **Tip:** To verify the connection, ask your AI agent to call the SonarQube MCP `ping_system` tool. For example: *"Ping the SonarQube MCP server."* > **Note:** No restart is required. Each Copilot cloud agent task runs in a fresh environment and picks up your updated `COPILOT_MCP_*` secrets automatically. > {% endtab %} > {% endtabs %} ## Use Sonar tools from the cloud agent Once connected, the GitHub Copilot cloud agent can call SonarQube MCP tools during its automated workflows. See the SonarQube MCP [Tools](/sonarqube-mcp-server/reference/tools.md) page for the full list of available tools. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.sonarsource.com/sonarqube-mcp-server/setup/quickstart-guides/github-copilot-cloud-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.