Skip to content
BranchesTags

Repository files navigation

xCloud Agent Skills

ClawHub Version MCP License: MIT xCloud OpenClaw

Operate xCloud in plain language from any AI agent. Ask "reboot my Hermes server", "renew SSL for example.com", or "scan example.com for vulnerabilities and show me the criticals" — the agent picks the right skill and chains the steps. No endpoints to memorize, no SDK to wire up.

Built by xCloud · Official GitHub · MCP Docs · User Guide · Install Guide · API Docs · OpenClaw + ClawHub Tutorial · Tutorial Video

This repository ships the xcloud Claude Code plugin (v4.1.0): five capability skills that pair with the xCloud MCP server — 110 native tools, one per authenticated Public API operation — with a bundled REST fallback for agents without MCP support.

New here? Start with the User Guide (task-first) or the Install & Usage Guide (full install, per-skill reference, smoke tests, routing rules).

The five skills

You never name them — the agent picks the right one from what you ask.

Skill Owns
xcloud:servers Servers, PHP, databases, cron, firewall/fail2ban, sudo users, services, provisioning WordPress and Git-deployed (Laravel/Node/PHP) sites
xcloud:sites Site lifecycle: status, backups, domains, cache, SSH, site cron, git settings, manual deploys, site deletion
xcloud:wordpress WP plugins/themes/updates, WP_DEBUG, magic login, site and team vulnerabilities, PageSpeed
xcloud:ssl SSL certificates: view, install, renew, status, delete
xcloud:account Current user, API tokens, Cloudflare integrations, blueprints, health

Skills are organized by capability, not URL root — each declares what it does not own with see xcloud:* cross-links so trigger keywords don't collide. See ADR 0001 for the rationale.

Connect the xCloud MCP (recommended)

The xCloud MCP server is the fastest way to give any agent full xCloud control — OAuth sign-in, no token to store, and built-in confirmation before every destructive operation. 110 tools, one per authenticated API operation.

Claude Code:

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

Then run /mcp → Authenticate and grant Read or Read & write.

Claude Desktop / claude.ai: Settings → Connectors → Add custom connector → name it xcloud, URL https://app.xcloud.host/mcp, sign in.

Cursor (~/.cursor/mcp.json) and any HTTP-capable MCP client:

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

Headless / CI: 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'

Verify with "who am I on xCloud?". Full details: MCP docs.

Install the skills plugin

The skills teach the agent xCloud's workflows — routing, safety guardrails, async polling, multi-step chains — on top of either transport (MCP or REST).

  1. Install in Claude Code:

    /plugin marketplace add xCloudDev/xcloud-agent-skills
/plugin install xcloud@xcloud-agent-skills
/reload-plugins

  2. Connect the account. If you added the MCP connector above, you're done — no token needed. Otherwise (REST fallback), get a token from the xCloud dashboard → Profile → API Tokens → Generate New Token and add it to your Claude Code settings:

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

    Use ~/.claude/settings.json (global) or a project-local .claude/settings.local.json (keep it out of git). Restart Claude Code so it picks up the token.

  3. Check it works. Ask Claude: "Check my xCloud API connection." A green light means you're ready.

If xCloud finds no connection, it will offer the MCP connector first, then guide you through scoped-token setup. Do not paste a production token into chat unless you are using a temporary, scoped token and no safer secret-store/runtime option exists.

Note: API-token management (list/revoke) and the /health probe are REST-only — the skills use the bundled curl wrapper for those even when the MCP is connected.

Agent Plugins 1.0.0

The portable package is at dist/agent-plugin/xcloud. It includes the five skills and the xCloud MCP connection in the standard layout:

xcloud/
├── plugin.json
├── mcp.json
└── skills/

Load that directory in a compatible Agent Plugins client. The package declares https://app.xcloud.host/mcp; the client manages OAuth authorization. Current compatible clients include ChatGPT and Codex, Cursor, GitHub Copilot, Kiro, and VS Code.

The repository's root /plugin marketplace entry remains the Claude Code package. For a local Codex test before the portable package is published, use the separate marketplace adapter:

codex plugin marketplace add ./dist/agent-plugin
codex plugin add xcloud@xcloud-agent-plugins

Release xcloud-agent-plugin.zip is the portable artifact for directory submission and clients that support local package import.

Build and validate it locally:

python3 dist/agent-plugin/build.py
python3 dist/agent-plugin/validate.py
for skill in dist/agent-plugin/xcloud/skills/*; do
  npx --yes skills-ref validate "$skill"
done

The portable distribution keeps every file reference within its skill. Before running its REST wrapper, an agent resolves SKILL_ROOT to the absolute directory containing the loaded SKILL.md; commands therefore do not depend on the user's working directory or Claude Code's ${CLAUDE_PLUGIN_ROOT} variable.

Known OAuth limitations: the production API Gateway currently returns x-amzn-remapped-www-authenticate instead of the required WWW-Authenticate header on an unauthenticated MCP 401. Clients that probe the OAuth well-known URLs directly work; strict clients may require the MCP URL to be added manually. Dynamic client registration currently grants mcp:read only even when mcp:write is requested, so newly registered portable clients must be treated as read-only until the production fixes are completed and verified. See the live regression checklist.

Other agent frameworks

The generated skills are plain Markdown plus a skill-local bash/curl wrapper:

git clone https://github.com/xCloudDev/xcloud-agent-skills.git
cd xcloud-agent-skills
python3 dist/agent-plugin/build.py
cp -r dist/agent-plugin/xcloud/skills/* /your/agent/skills/

Agents that support MCP should load the root mcp.json; other agents can use the skill-local REST wrapper and XCLOUD_API_TOKEN.

Example requests

You describe what you want; Claude chains the steps.

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.
Show me team-wide WordPress vulnerabilities across all xCloud sites.
Deploy the latest Git commit for example.com.

Multi-step workflows — each is a single request:

Audit example.com — is it up, is SSL healthy, any vulnerabilities, and how's performance?
example.com is throwing 502 errors — what's going on?
I just provisioned shop.example.com — set up HTTPS and confirm it's serving.

If Claude ever reaches for the wrong area, name it: Using xcloud:ssl, renew the cert for example.com.

Authentication & scopes

MCP (recommended): browser OAuth with two grant levels — Read (mcp:read) or Read & write (mcp:write). Access is team-scoped and every connection shows up in the dashboard's API key management for one-click revocation. Every destructive MCP tool additionally requires per-action confirmation.

REST fallback: the skills authenticate with a Sanctum personal access token (Bearer auth). Generate one in the xCloud dashboard → Profile → API Tokens → Generate New Token, choosing scopes:

Scope Grants
read:sites / write:sites Reads / writes under /sites/* and /ssl-certificates/*
read:servers / write:servers Reads / writes under /servers/*
* Full access, including token management

Prefer the narrowest scopes that cover your use. The base URL is environment driven (XCLOUD_API_BASE_URL, default https://app.xcloud.host) — point it at a local or white-label host without touching any skill. Full details in plugins/xcloud/reference/auth.md.

API & MCP reference

  • MCP endpoint: https://app.xcloud.host/mcp (Streamable HTTP) — docs
  • MCP tools: 110 — full parity with the authenticated REST surface; tool names mirror endpoint paths (servers_reboot, sites_ssl_renew, …)
  • API docs: https://app.xcloud.host/api/v1/docs (every endpoint, request/response schema, interactive try-it console)
  • Base URL: https://app.xcloud.host/api/v1
  • Auth: MCP OAuth, or Bearer token (Sanctum)
  • Rate limit: 60 requests/minute authenticated (10/min unauthenticated)

Useful links

Link Use it for
xCloud Product landing page and hosting platform overview
xCloud MCP Docs Connect the MCP server from any agent (OAuth or API key)
xCloud Dashboard Generate API tokens and manage hosting resources
User Guide Task-first examples for using the skills with an agent
Install & Usage Guide Full install steps, routing rules, and smoke tests
API Docs Public API reference and schemas
OpenClaw + ClawHub Tutorial Step-by-step xCloud guide to installing skills from ClawHub
xCloud Tutorial Video Video walkthrough for the xCloud/OpenClaw skills workflow
xCloud YouTube xCloud tutorials, walkthroughs, and release videos
GitHub Source, issues, changelog, and contribution flow

Testing

Each skill ships a read-only tests/smoke.sh. Point it at a real resource and it exercises that skill's core reads end-to-end:

export XCLOUD_API_TOKEN="your-token"
export XCLOUD_TEST_SERVER_UUID="..."   # for the servers suite
plugins/xcloud/skills/servers/tests/smoke.sh

The suites are read-only and tolerate optional sub-resources that a given server/site type doesn't support.

Legacy: Python SDK & CLI

The installable artifact is the skill set above. The Python SDK, async helpers, and shell CLI under src/ predate the skills (v1.x) and are kept for direct scripting use. They are not part of the xcloud plugin and are not copied into it.

from src.xcloud_sdk import XCloudAPI, XCloudDeployer

api = XCloudAPI()              # reads XCLOUD_API_TOKEN
for s in api.list_servers()['items']:
    print(s['name'], s['ip_address'])

deployer = XCloudDeployer(api)
health = deployer.get_fleet_health()
print("Total sites:", health['sites']['total'])
./src/xcloud-cli.sh server list
./src/xcloud-cli.sh site status <site-uuid>
  • src/xcloud_sdk.py — XCloudAPI (low-level client) + XCloudDeployer (provisioning, fleet health, batch backups).
  • src/xcloud_async.py — polling, persistent state, rate-limit backoff.
  • src/xcloud-cli.sh — interactive server/site management.
  • Recovery patterns live in docs/ERROR-HANDLING.md; real-world scenarios in docs/AGENT-SCENARIOS.md.

Install the SDK dependencies with pip install -r requirements.txt.

Security

  • Store the token in agent/CLI settings or a secure credential file — never commit it. .env* and .claude/settings.local.json are gitignored.
  • Use scoped tokens (avoid * unless you need token management), rotate regularly, and revoke tokens that have been exposed.
  • Each request also passes a per-resource policy check — a 403 with a valid token means a missing team permission, not a bad token.

Full guidance: SECURITY.md.

Links

License

MIT — see LICENSE.

About

Portable skills for xCloud agent workflows. Works with Claude Code, OpenCode, and any agent that reads markdown prompts.

Resources

Readme
MIT license

Security policy

Security policy
Activity
Custom properties

Stars

7 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

Packages

Used by

Contributors

Languages