# xCloud — auth.md xCloud is a cloud hosting and server-management platform. It provisions servers (on xCloud or a customer's own cloud provider), installs and manages sites and apps (WordPress, Laravel, Docker one-click apps), and handles SSL, backups, DNS, and team access. Every resource belongs to a customer team, and an agent always acts for an existing customer. This file follows the auth.md convention (https://workos.com/auth-md). It is written for agents and for the humans configuring them. ## auth.md registration: not offered xCloud does not advertise any auth.md registration method (`identity_assertion`, `service_auth`, or `anonymous`). `https://app.xcloud.host/.well-known/oauth-authorization-server` has no `agent_auth` block, and there is no `/agent/identity` or claim endpoint. Do not attempt agent registration against xCloud; use one of the two paths below, both of which work today. This file will link production registration metadata if that changes. ## 1. MCP with OAuth (recommended) Endpoint: `POST https://app.xcloud.host/mcp` (MCP Streamable HTTP, JSON-RPC over POST). The server does not offer a server-to-client SSE stream; `GET` with `Accept: text/event-stream` returns 405, and a plain `GET` redirects to the human setup page. Authentication is OAuth 2.1 authorization code with PKCE (`S256` only). Discover it the standard way and treat the discovered documents as authoritative over anything written here: - Protected resource metadata (RFC 9728): `https://app.xcloud.host/.well-known/oauth-protected-resource/mcp`. Follow its `authorization_servers` entry. - Authorization server metadata (RFC 8414): `https://app.xcloud.host/.well-known/oauth-authorization-server`. Use the `authorization_endpoint`, `token_endpoint` and `registration_endpoint` it lists. - An unauthenticated `POST /mcp` returns `401` with `WWW-Authenticate: Bearer resource_metadata="…"` pointing at the protected resource document. - Dynamic client registration (RFC 7591): `POST https://app.xcloud.host/oauth/register`. Clients are public (`token_endpoint_auth_method: none`), with 1 to 10 redirect URIs: `https` on any host, `http` on loopback only, or a private-use scheme such as `cursor://` or `vscode://`. OAuth Client ID Metadata Documents (a URL as `client_id`) are not accepted. - Scopes: `mcp:read` (default) and `mcp:write`. The user approves in their browser, chooses read-only or read and write, and picks which of their teams the grant covers. - Access tokens last 15 days and refresh tokens 30 days. A token issued with a `resource` parameter is bound to that endpoint (RFC 8707); one issued without it works on `/mcp`. Grants are revocable from the user's API tokens page. Setup instructions for Claude Code, Claude Desktop, Cursor and other clients: `https://app.xcloud.host/mcp/docs`. The public tool catalog is `GET https://app.xcloud.host/mcp/toolsets`; clients that cap tool counts can connect with `?profile=compact` or `?toolsets=sites,servers`. ## 2. Personal access token (for clients without browser sign-in) A human creates a token at `https://app.xcloud.host/user/api-tokens` (Profile → API Tokens) and gives it to the agent. Send it as `Authorization: Bearer `. - Tokens do not expire until revoked. They contain a `|`, so quote them in shells. - Abilities: `read:servers`, `read:sites`, `read:billing`, `read:addons`, `write:servers`, `write:sites`, `write:addons`, `read:tokens`, `write:tokens`. A full-access `*` token covers all of them. - For MCP the token must carry `mcp:invoke` explicitly; `*` alone does not open `/mcp`. `mcp:invoke` only opens the door: each tool still needs the ability its Public API operation requires, so a sensible read-only token is `mcp:invoke` + `read:servers` + `read:sites`, and writes need the matching `write:` ability. `mcp:profile:compact` and `mcp:toolset:` narrow the MCP tool surface. - Use the token on the Public API at `https://app.xcloud.host/api/v1` (OpenAPI: `https://app.xcloud.host/api/v1/openapi.yaml`, reference: `https://app.xcloud.host/api/v1/docs`) or on `/mcp`. - The xCloud agent skills plugin for Claude Code reads the token from the `XCLOUD_API_TOKEN` environment variable: `https://app.xcloud.host/agent/skills`. ## Teams Every token and OAuth grant has a default team and may be granted additional teams by the user at creation or consent time. Requests run against the default team unless you pick another granted team: `GET https://app.xcloud.host/api/v1/teams` lists them, the Public API accepts `X-Team-Id: `, and MCP tools accept a `team` argument. A token never sees teams it was not granted. ## Rate limits - `/mcp`: 120 requests per minute and 1,200 per hour per token. - Public API: 60 requests per minute per token; 10 per minute per IP when unauthenticated. - `POST /oauth/register`: 5 per minute and 30 per hour per IP. Over the limit you get HTTP `429` with `Retry-After`; MCP tool results carry `retry_after` in seconds. Back off accordingly. ## Credential handling Check for an existing MCP connection or `XCLOUD_API_TOKEN` before asking for anything. Prefer the OAuth path; do not ask a user to paste a token into chat when their client supports browser sign-in. Read tokens from the environment or a secret store at the moment of use, and never log, print, or commit them. ## Accounts Humans sign up at `https://app.xcloud.host/register` and sign in at `https://app.xcloud.host/login`. Agents cannot create accounts, and a payment method is required before servers can be provisioned. ## Legal and contact - Terms: `https://app.xcloud.host/terms-and-services` - Privacy: `https://app.xcloud.host/privacy-policy` - Documentation: https://xcloud.host/docs/ - Support: support@xcloud.host Last reviewed: 2026-10-12