# How to Connect Grok to xCloud MCP

> Connect Grok Build, xAI's terminal agent, to xCloud with one grok mcp add command or a config.toml entry, then deploy, back up, update and fix sites by asking.

Grok Build is xAI's coding agent for the terminal. Connected to xCloud through the MCP server, it deploys repositories, takes backups, updates WordPress, renews SSL and diagnoses failures from the shell you already work in.

This guide covers the connection only. For what Grok can do once it is connected, with one guide per hosting job, see the [Grok and xCloud guide](/agents/grok/). 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).
- Grok 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 grok. The first time it calls xCloud, a browser opens on the xCloud approval screen, where you tick the teams and choose Read-only or Full access. Add `--scope` project to save the entry in .grok/config.toml for one repository instead.

```bash
grok mcp add --transport http xcloud https://app.xcloud.host/mcp
```

## Step 2: Or edit ~/.grok/config.toml

Add this table to ~/.grok/config.toml, then run grok mcp doctor xcloud to check the connection. The url key is the one for HTTP servers.

```toml
[mcp_servers.xcloud]
url = "https://app.xcloud.host/mcp"
```

## 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. Put it in an environment variable the machine starts Grok with, such as XCLOUD_TOKEN in a systemd EnvironmentFile or your shell profile, and pass a reference to it with `--header`. Keep the single quotes so the shell leaves ${XCLOUD_TOKEN} alone: Grok expands ${VAR} in headers when it loads the config, so the token itself never lands in your shell history or in config.toml. Run grok mcp doctor xcloud to confirm it works.

```bash
grok mcp add --transport http --header 'Authorization: Bearer ${XCLOUD_TOKEN}' xcloud https://app.xcloud.host/mcp
```

## Approve access in your browser

The first time Grok 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**. Grok Build runs a browser OAuth flow on first use and stores the tokens under ~/.grok, so nothing goes into config.toml. A headless machine passes an API key with the mcp:invoke scope and the abilities it needs as a header.

![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 Grok:

```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 Grok 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. Grok'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 [Grok and xCloud guide](/agents/grok/), 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

- This page covers Grok Build, the terminal agent. Grok at grok.com has its own connector settings: check Grok's connector settings for a custom MCP connector and use the same server URL, https://app.xcloud.host/mcp.
- Remote servers need `--transport` http on the command line. Without it, grok mcp add treats the argument as a local command.
- OAuth tokens are kept in ~/.grok/mcp_credentials.json. Keep that file out of version control and out of backups you share.
- If xCloud tools do not appear, run grok mcp doctor xcloud, then restart grok.

## Frequently asked questions

### How do I connect Grok Build to xCloud?

Run grok mcp add `--transport` http xcloud https://app.xcloud.host/mcp in your terminal, then start grok and ask who you are on xCloud. A browser opens the first time so you can approve the teams and the access level.

### What is the config.toml form for xCloud?

Add a [mcp_servers.xcloud] table to ~/.grok/config.toml with url set to https://app.xcloud.host/mcp. Then run grok mcp doctor xcloud to check the connection. Use grok mcp add with `--scope` project to keep the entry in a repository's .grok/config.toml instead.

### Can I use xCloud from Grok at grok.com?

Yes, through a custom connector. Go to grok.com/connectors, choose New Connector, then Custom, enter https://app.xcloud.host/mcp as the server URL and sign in with xCloud when the browser asks; xAI's connectors page documents that flow. On Grok Business and Enterprise a team admin has to provision the connector in the cloud console before members can use it. The rest of this page covers Grok Build, the terminal agent.

### Do I need an xCloud API key for Grok Build?

Not when you sign in with OAuth. Servers that need OAuth open a browser flow on first use. 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 pass it with the `--header` flag.

## Next steps

- [Grok and xCloud: every job guide](/agents/grok/)
- [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/).