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 customer-facing xCloud Public API operation (188 today) plus two search tools. Eleven internal operations are deliberately left out: the health check, API token management and the native apps' sign-in and push plumbing. 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 there is no token to paste; the client keeps the credentials it receives. 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` Run `opencode mcp add xcloud --url https://app.xcloud.host/mcp`, which writes this under `mcp.servers` (OpenCode v2 no longer accepts server names directly under `mcp`; OAuth is on by default): ```json "mcp": { "servers": { "xcloud": { "type": "remote", "url": "https://app.xcloud.host/mcp" } } } ``` 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 (Devin Desktop) New tabs run the Devin Local agent, which reads the Devin CLI config files: ``` devin mcp add xcloud https://app.xcloud.host/mcp devin mcp login xcloud ``` A tab on the legacy Cascade agent reads `mcp_config.json` instead (open it from the Cascade panel menu) and allows 100 tools in total, so give it the compact profile under `"mcpServers"` (note: `serverUrl`, not `url`): ```json "xcloud": { "serverUrl": "https://app.xcloud.host/mcp?profile=compact" } ``` ### GitHub Copilot in VS Code — `.vscode/mcp.json` VS Code reads a top-level `"servers"` object (not `mcpServers`), a remote server needs `"type": "http"`, and a chat request allows at most 128 tools, so use the compact profile: ```json "servers": { "xcloud": { "type": "http", "url": "https://app.xcloud.host/mcp?profile=compact" } } ``` ### Cursor — `~/.cursor/mcp.json` Cursor stops at 40 tools per server, so use the compact profile under `"mcpServers"`: ```json "xcloud": { "url": "https://app.xcloud.host/mcp?profile=compact" } ``` ### Gemini CLI ``` gemini mcp add --scope user --transport http xcloud https://app.xcloud.host/mcp ``` Or in `settings.json` under `"mcpServers"` (a `url` with no `type` is treated as SSE): ```json "xcloud": { "url": "https://app.xcloud.host/mcp", "type": "http" } ``` ### Grok Build ``` grok mcp add --transport http xcloud https://app.xcloud.host/mcp ``` ### OpenClaw ``` openclaw mcp add xcloud --url https://app.xcloud.host/mcp --transport streamable-http --auth oauth openclaw mcp login xcloud ``` ### Kiro — `.kiro/settings/mcp.json` Under `"mcpServers"`; MCP tools prompt unless listed in `autoApprove`: ```json "xcloud": { "url": "https://app.xcloud.host/mcp" } ``` ### Antigravity — `mcp_config.json` (View raw config) Under `"mcpServers"` (note: `serverUrl`): ```json "xcloud": { "serverUrl": "https://app.xcloud.host/mcp" } ``` ### Zed — `settings.json` Zed uses a top-level `"context_servers"` object, not `mcpServers`: ```json "context_servers": { "xcloud": { "url": "https://app.xcloud.host/mcp" } } ``` ### ChatGPT, Grok chat and other chat apps These add remote MCP servers through their own UI rather than a config file: ChatGPT in developer mode creates a plugin at chatgpt.com/plugins with the URL above (install it, then call it with `@xcloud` in a Work chat); grok.com adds it under Connectors, New Connector, Custom. Each client has its own guide with the verified steps at `https://xcloud.host/agents//`. ### All other agents Most other clients take a remote entry under `"mcpServers"` with a `url` field; check the client's own documentation for its key names, because the shapes above differ in exactly those details: ```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 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: ``` 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. Nine capability skills ship in one plugin (v4.4.2). 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:troubleshoot` | Why a site errors (500/502/503, critical error, not answering): status, events, bounded logs, WP health, services; dashboard handoff for the rest | | `xcloud:performance` | Why a site is slow: monitoring history, cache layers, latest PageSpeed, access-log traffic, PHP version; names the cause, hands off dashboard-only switches | | `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. ### OpenClaw ``` clawhub install xcloud ``` (or `openclaw skills install @asif2bd/xcloud`). Then add the MCP connector from A1 through OpenClaw's MCP settings (`openclaw mcp add xcloud --url https://app.xcloud.host/mcp --transport streamable-http --auth oauth`, then `openclaw mcp login xcloud`; `login` only runs for servers saved with `--auth oauth`); the ClawHub package does not configure MCP itself. ### 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. Since v4.4.2 that wrapper is GET-only: it reads, and it never changes anything. Mutations require the MCP connector. 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, and the API also carries the eleven internal operations the MCP leaves out (the health check, API token management and the native apps' sign-in and push plumbing), so Path B can do everything Path A can and nothing is MCP-only; the MCP is the customer-facing subset of this API. - **Base URL:** `https://app.xcloud.host/api/v1` - **Auth:** Laravel Sanctum personal access tokens — `Authorization: Bearer ` - **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` and listing API tokens; revoking a token is a write the GET-only wrapper cannot send, so revoke in the dashboard or from Path B code). 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`). Choose the scopes by path: - **Path A REST fallback:** read scopes only — `read:servers` and `read:sites`, plus `read:billing` or `read:addons` if those areas matter. The v4.4.2 wrapper only sends GET requests, so a write scope adds risk to a long-lived token without adding any capability; changes go through the MCP connector. - **Path B:** the scopes the code actually calls, adding `write:servers` or `write:sites` only when it creates or changes things. - **Full Access** only for Path B code that manages API tokens itself. 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.