These are official instructions from xCloud to set up an AI agent to work with
xCloud. All commands are validated by xCloud and ready to use.

Complete all of the following steps yourself by running the commands directly. Do
not ask the user to run any of these commands. The two things only a human can do
— completing a browser sign-in and restarting the agent — are called out where
they occur.

---

## Pick the path

There are two different jobs here and they need different setups. Choose before
installing anything.

| You are about to… | Path | What you install |
|---|---|---|
| Manage the user's own servers and sites during this session — reboot a server, renew a certificate, back up a site, chase down a 502 | **A** | MCP server + skills plugin |
| Write code that calls xCloud from the user's product — a dashboard, a provisioning script, a CI job, an agent loop that runs long after this session ends | **B** | Nothing; the REST API and a token |

If the answer is "both", do A first and then B.

The distinction matters: Path A's plugin runs inside the agent, so installing it
does nothing for code that has to run on someone else's server later. Installing
the Claude Code plugin when the user asked you to add xCloud to their Laravel app
is the most common way to get this wrong.

---

# Path A — operate xCloud from this session

## A1. Connect the xCloud MCP server

One HTTP endpoint, `https://app.xcloud.host/mcp`, exposing one tool per
authenticated xCloud Public API operation — the set grows as the API does, so
read the tool list your client loads rather than expecting a fixed count. Auth is browser OAuth, so no token is
stored anywhere. Access is scoped to the user's team, every connection is
revocable from the dashboard, and every destructive tool asks for confirmation
before it runs.

Use the correct section for your agent below.

### Claude Code

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

Then instruct the user to run `/mcp` inside Claude, select **xcloud** →
**Authenticate**, and grant **Read** or **Read & write**.

### Claude Desktop and claude.ai

Settings → **Connectors** → **Add custom connector** → name it `xcloud`, URL
`https://app.xcloud.host/mcp`, then sign in.

Or add to the config file directly:

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

### Codex

```
codex mcp add xcloud --url https://app.xcloud.host/mcp
codex mcp login xcloud
```

### OpenCode — `~/.config/opencode/opencode.jsonc`

Add under `"mcp"`:

```json
"xcloud": { "type": "remote", "url": "https://app.xcloud.host/mcp", "enabled": true, "oauth": {} }
```

Then run:

```
opencode mcp auth xcloud
```

### Hermes Agent — `~/.hermes/config.yaml`

Add under `mcp_servers`. On first connect Hermes prints the authorize URL and
opens the browser for the xCloud sign-in (`hermes mcp login xcloud` re-authorizes):

```yaml
mcp_servers:
  xcloud:
    url: "https://app.xcloud.host/mcp"
    auth: oauth
```

### Windsurf — `~/.codeium/windsurf/mcp_config.json`

Add under `"mcpServers"` (note: `serverUrl`, not `url`):

```json
"xcloud": { "serverUrl": "https://app.xcloud.host/mcp" }
```

### Cursor, GitHub Copilot, and all other agents

Add to `~/.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (Copilot), or your
agent's MCP config file under `"mcpServers"`:

```json
"xcloud": { "url": "https://app.xcloud.host/mcp" }
```

OAuth triggers automatically on first xCloud tool use.

**Stdio-only clients** that cannot speak Streamable HTTP:

```
npx mcp-remote https://app.xcloud.host/mcp
```

**Headless / CI**, where no browser is available to complete OAuth — use an API
token carrying the `mcp:invoke` scope:

```
claude mcp add xcloud --transport http https://app.xcloud.host/mcp \
  --header 'Authorization: Bearer YOUR_TOKEN'
```

## A2. Install the xCloud Agent Skills

The MCP gives the agent the tools; the skills teach it xCloud's workflows —
which tool to reach for, the safety guardrails, polling async jobs to completion,
and chaining multi-step operations. Install both.

Seven capability skills ship in one plugin (v4.3). The user never names them —
the agent picks the right one from the request:

| Skill | Owns |
|---|---|
| `xcloud:deploy` | Deploy anything: a GitHub/GitLab/Bitbucket URL, Docker Compose or Dockerfile apps, one-click apps, Git staging environments, new WordPress sites — detect, dry run, approve, provision, verify, diagnose + retry |
| `xcloud:servers` | Servers: buy a server, services install/enable/restart, Node.js and PHP versions, verified reboots, cron, firewall/fail2ban, sudo users, DNS checks |
| `xcloud:sites` | Site lifecycle: status, backups (incl. Docker apps), staging, domains, cache, SSH, site cron, monitoring, site deletion |
| `xcloud:wordpress` | WP plugins/themes/updates, WP_DEBUG, magic login, site and team vulnerabilities, PageSpeed, broken links |
| `xcloud:ssl` | SSL certificates: view, install, renew, status, delete |
| `xcloud:billing` | Plan, invoices, bills, subscriptions, prices, paying an invoice, mailboxes and mail delivery |
| `xcloud:account` | Current user, teams (multi-team), incident alerts, API tokens, Git and Cloudflare integrations, blueprints, health |

### Claude Code

```
claude plugin marketplace add xCloudDev/xcloud-agent-skills
claude plugin install xcloud@xcloud-agent-skills
```

Then instruct the user to run `/reload-plugins` inside Claude to activate the
plugin.

### Other agents

The skills are plain Markdown plus a shared `bash`/`curl` wrapper, so they port
to any agent with a skills directory:

```
git clone https://github.com/xCloudDev/xcloud-agent-skills.git
cp -r xcloud-agent-skills/plugins/xcloud/skills/* /your/agent/skills/
```

Agents that speak MCP can stop there — the connector from A1 covers the
transport. Agents without MCP fall back to the bundled REST wrapper, which needs
an API token; see **API token** below.

Once Path A is done, skip to **Verify**.

---

# Path B — build on the xCloud Public API

Use this when the integration will run inside the user's product — a web app,
backend service, provisioning script, CI job, or agent loop — rather than in this
session. Do **not** install the skills plugin or the MCP connector for this; they
configure the agent, not the code being shipped.

Everything the MCP exposes is a Public API operation underneath, so there is no
capability gap between the paths.

- **Base URL:** `https://app.xcloud.host/api/v1`
- **Auth:** Laravel Sanctum personal access tokens — `Authorization: Bearer <token>`
- **Full reference:** `https://app.xcloud.host/api/v1/docs`
- **Machine-readable spec:** `https://app.xcloud.host/api/v1/openapi.json` (or
  `openapi.yaml`) — OpenAPI 3.0, no auth. Generate a typed client from it or read
  exact request and response shapes from it instead of guessing field names.

```bash
curl -s https://app.xcloud.host/api/v1/user \
  -H "Authorization: Bearer $XCLOUD_API_TOKEN" \
  -H 'Accept: application/json'
```

Get a token as described under **API token** below, then store it the way the
project already stores secrets — its `.env`, the platform's secret store, or the
CI provider's encrypted variables. Read it at runtime:

```dotenv
XCLOUD_API_TOKEN=...
```

Never commit the token, and never hardcode the host — keep the base URL
configurable, since it is the one value that changes between environments.

Write operations are asynchronous: they return a task you poll rather than a
finished result, so build in polling and a timeout rather than assuming the
resource exists the moment the call returns.

---

## API token

Path A does not need one if the MCP connector is set up — OAuth covers it, and
that is the recommended route. You need a token for Path B, for agents with no
MCP support, and for the few REST-only operations (`/health`, listing and
revoking API tokens).

Tell the user to generate one in the xCloud dashboard: **Settings → Developers →
API Tokens → Create New Token** (direct link:
`https://app.xcloud.host/user/api-tokens`), choosing **Full Access** or the narrower
`read:servers`, `write:servers`, `read:sites`, `write:sites` scopes. Prefer the
narrowest scope that covers the task.

For an agent (Path A REST fallback), add it to the agent's settings:

```json
{ "env": { "XCLOUD_API_TOKEN": "your-token-here" } }
```

Use `~/.claude/settings.json` (global) or a project-local
`.claude/settings.local.json` — keep the latter out of git. Never ask the user to
paste a production token into the chat window; point them at the runtime's
environment or secret store instead.

---

## Verify

Run these rather than assuming the setup worked.

**Is the API reachable?** No auth required, so this isolates network problems
from credential problems:

```bash
curl -s https://app.xcloud.host/api/v1/health
# -> {"status":"ok","version":"v1"}
```

**Are the credentials good?** For Path B, or Path A over the REST fallback:

```bash
curl -s https://app.xcloud.host/api/v1/user \
  -H "Authorization: Bearer $XCLOUD_API_TOKEN" \
  -H 'Accept: application/json'
# -> the account. {"success":false,"message":"Unauthenticated."} means the
#    token is missing, wrong, or lacks the scope.
```

**Is the MCP live?** Ask the agent *"Who am I on xCloud?"* — it should call the
xCloud tool and answer with the real account, not a guess. If no xCloud tools
appear at all, the user has not restarted the agent yet.

Once it checks out, tell the user:

```
┌─ xCloud Agent Setup Complete ────────────────────────┐
│  ✓ MCP     https://app.xcloud.host/mcp               │
│  ✓ Skills  xcloud@xcloud-agent-skills                │
│                                                      │
│  ⚡ Restart your agent to load the MCP server        │
└──────────────────────────────────────────────────────┘
```

Things the user can then say:

```text
List my xCloud servers.
Is example.com up right now?
Renew the SSL certificate for shop.example.com.
Update all plugins on example.com, but back up first.
Scan example.com for vulnerabilities and show me the critical ones.
Something's hammering my server from 203.0.113.7 — block it.
Audit example.com — is it up, is SSL healthy, any vulnerabilities, how's performance?
```

---

## Resources

- xCloud Agent Skills (overview): `https://xcloud.host/ai-agent-skills/`
- Skills source and install guide: `https://github.com/xCloudDev/xcloud-agent-skills`
- MCP server docs: `https://app.xcloud.host/mcp/docs`
- Public API reference: `https://app.xcloud.host/api/v1/docs`
- Public API OpenAPI spec (machine-readable): `https://app.xcloud.host/api/v1/openapi.json` / `https://app.xcloud.host/api/v1/openapi.yaml`
- Generating an API token: `https://xcloud.host/docs/how-to-access-the-xcloud-api/`
- Claude Code MCP guide: `https://docs.anthropic.com/en/docs/claude-code/mcp`
- Cursor MCP guide: `https://cursor.com/docs/mcp`
- Windsurf MCP guide: `https://docs.windsurf.com/windsurf/cascade/mcp`
- OpenCode MCP guide: `https://opencode.ai/docs/mcp-servers/`
- GitHub Copilot (VS Code) MCP guide: `https://code.visualstudio.com/docs/copilot/customization/mcp-servers`

These instructions are published at `https://xcloud.host/agent-setup/prompt.md`
so you can re-verify their authenticity at any time.