# How to Connect Gemini CLI to xCloud MCP

> Connect Gemini CLI to xCloud with one gemini mcp add command or a settings.json entry, then deploy, back up, update and fix sites by asking.

Gemini CLI is Google's command-line AI agent. Connected to xCloud through the MCP server, it deploys repositories, takes backups, updates WordPress, renews SSL and diagnoses failures from the terminal you already work in.

This guide covers the connection only. For what Gemini CLI can do once it is connected, with one guide per hosting job, see the [Gemini CLI and xCloud guide](/agents/gemini-cli/). The xCloud side is free with every account, including the free plan.

## What you need

- An xCloud account. If you do not have one yet, [sign up for free](https://app.xcloud.host/register).
- Gemini CLI installed and signed in.
- A browser for the OAuth sign-in. A machine without a browser can use an API key instead; the steps below show both.

The xCloud MCP server lives at one endpoint, `https://app.xcloud.host/mcp`, over the MCP Streamable HTTP transport. The same setup also lives in your dashboard under **Settings → Developers → MCP**.

## Step 1: Add the xCloud MCP server

Run this in your terminal, then start gemini. The `--scope` user flag writes the server to ~/.gemini/settings.json so it is available in every project; without it, gemini mcp add writes to the current project's .gemini/settings.json and refuses to run from your home directory. The first time it calls xCloud it finds the OAuth endpoints, opens your browser on the xCloud approval screen and asks you to tick the teams and choose Read-only or Full access.

```bash
gemini mcp add --scope user --transport http xcloud https://app.xcloud.host/mcp
```

## Step 2: Or edit settings.json

Add this to ~/.gemini/settings.json for every project, or to .gemini/settings.json in one project. This is the entry gemini mcp add writes: url plus type set to http. The older httpUrl key still works, but a url without a type is treated as an SSE server and will not connect. If the browser sign-in does not start, type /mcp auth xcloud inside Gemini CLI.

```json
{
  "mcpServers": {
    "xcloud": {
      "url": "https://app.xcloud.host/mcp",
      "type": "http"
    }
  }
}
```

## Step 3: No browser? Use an API key

For a headless machine, create a token with the mcp:invoke scope plus the read abilities for the areas it will use (read:servers and read:sites, with read:billing and read:addons for billing and add-on tools) and the matching write: abilities if it should change things in Settings, Developers, API Tokens and send it in the headers field. Keep the token out of version control, and keep the quotes: xCloud tokens contain a pipe character.

```json
{
  "mcpServers": {
    "xcloud": {
      "url": "https://app.xcloud.host/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

## Approve access in your browser

The first time Gemini CLI reaches for an xCloud tool, your browser opens on the xCloud authorization screen. Tick the teams the connection may act on and choose **Read-only** or **Full access**. Gemini CLI detects the 401 from xCloud and runs the OAuth flow in your browser, so there is no token to paste into settings.json; Gemini CLI keeps the OAuth tokens it receives in its own credential store. A headless machine sends an API key with the mcp:invoke scope and the abilities it needs in the headers field.

![The xCloud authorization screen: the signed-in account, the teams to tick, and the choice between Full access and Read-only](/_landing/docs/how-to-connect-xcloud-mcp-to-ai-agent-oauth-teams.png)

Every connection is listed with your [API keys](https://app.xcloud.host/user/api-tokens), so you can revoke it at any time. Read-only is enough for reports and checks; choose Full access when you want the agent to deploy, update or change things. With Full access, routine actions such as a backup, a cache purge or a service restart run without an xCloud prompt, while creating, deploying, updating, rebooting, deleting or buying still waits for your confirmation.

## Check it worked

Ask Gemini CLI:

```text
Who am I on xCloud?
```

It should answer with your real account name, email and teams, not a guess. If it says it has no xCloud tools, re-check the step above and restart the client.

## What Gemini CLI can do on xCloud

On the xCloud side, reads run straight away, and anything that creates, deploys, updates, reboots, deletes or buys is previewed first and waits for your confirmation. Gemini CLI's own approval prompts, where it has them, apply on top of that. A few prompts to start with:

```text
Deploy https://github.com/acme/shop to my Frankfurt server and show me the dry run before you create anything.
```

```text
Update all plugins on example.com, but take a backup first and confirm the homepage still loads afterwards.
```

```text
The last deploy of the API site failed. Diagnose it, fix the build command and retry on the same site.
```

There is a guide for each hosting job, from deploying a repository to fixing a 502, on the [Gemini CLI and xCloud guide](/agents/gemini-cli/), and a longer prompt library in [What You Can Ask xCloud MCP to Do](/what-you-can-ask-xcloud-mcp-to-do/).

## Good to know

- In settings.json a streamable HTTP server is url plus type set to http, which is what gemini mcp add writes; the older httpUrl key still works. A url without a type is treated as an SSE server and will not connect.
- Do not set trust to true on the xcloud entry. It makes Gemini CLI skip its own tool confirmation dialogs.
- The browser sign-in redirects to a localhost port, so it needs a browser on the same machine. On a remote or headless host, use the API-key form.
- Gemini CLI names tools mcp_xcloud_ followed by the operation name. Use includeTools or excludeTools on the entry if you want a smaller tool list.

## Frequently asked questions

### How do I connect Gemini CLI to xCloud?

Run gemini mcp add `--scope` user `--transport` http xcloud https://app.xcloud.host/mcp in your terminal, then start gemini and ask who you are on xCloud. The `--scope` user flag registers the server for every project instead of only the current one. Approve the access level in the browser tab that opens the first time.

### What is the settings.json form for xCloud?

Under mcpServers add an xcloud entry with url set to https://app.xcloud.host/mcp and type set to http, which is what gemini mcp add writes. Use ~/.gemini/settings.json for every project or .gemini/settings.json for one. The older httpUrl key still works; a url without a type means SSE.

### Do I need an xCloud API key for Gemini CLI?

Not when you sign in with OAuth. Gemini CLI finds the authorization endpoints itself and opens your browser. An API key is only for machines without a browser: create a token with the mcp:invoke scope plus the read abilities for the areas it will use (read:servers and read:sites, with read:billing and read:addons for billing and add-on tools) and the matching write: abilities if it should change things and send it in the headers field as an Authorization Bearer value.

### What if the sign-in does not start?

Type /mcp auth xcloud inside Gemini CLI to start the OAuth flow by hand. The redirect goes to a localhost port, so run it on a machine that has a browser. Run gemini mcp list to check that the xcloud server is registered.

## Next steps

- [Gemini CLI and xCloud: every job guide](/agents/gemini-cli/)
- [How to connect xCloud MCP to your AI agent](/docs/how-to-connect-xcloud-mcp-to-ai-agent/) for the other clients
- [Multi-team API tokens and MCP access](/docs/multi-team-api-tokens-and-mcp-access/)

If you run into any issues connecting, feel free to reach out to our [support team](/docs/access-built-in-support-portal-in-xcloud/).