Connect xCloud to your AI assistant

The xCloud MCP server lets Claude, Cursor, or any MCP-compatible client manage your servers and sites. It’s built into xCloud — connect in seconds.

Server URL

https://app.xcloud.host/mcp

Add this URL to your client. Most clients authenticate over OAuth: the browser opens, you approve the access you want to grant, and the connection is live — no API key to create or store. If your client can’t do browser sign-in, use an API key.

Add the server URL

Point your client at the endpoint. No token, no headers.

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

Then run /mcp inside Claude Code and pick Authenticate.

Open Settings → Connectors → Add custom connector, name it xcloud, and paste the URL:

https://app.xcloud.host/mcp

Claude Desktop opens the browser sign-in for you.

Open Settings → MCP → Add new MCP server, or add this to ~/.cursor/mcp.json:

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

Cursor shows a Needs login prompt — click it to sign in.

Any client that supports the MCP Streamable HTTP transport can connect. Point it at the URL — it discovers the OAuth endpoints automatically:

https://app.xcloud.host/mcp

Client only supports local (stdio) servers? Bridge with npx mcp-remote https://app.xcloud.host/mcp.

Approve access in your browser

xCloud opens in a browser tab. Sign in if you aren’t already, then grant one of:

Read (mcp:read) — view servers, sites, account, and billing details (plan, invoices, payment methods).
Read & write (mcp:write) — view, plus make changes such as deploying a site or restarting a service.

Access is scoped to the team you’re signed in to, and every connection is listed with your API keys so you can revoke it at any time.

Done. Ask your assistant “who am I on xCloud?” to check the connection.

Client doesn’t support browser sign-in? Use an API key

Create an API key

Create an xCloud access token with the explicit mcp:invoke scope. Add read:servers and read:sites to let the assistant view things, or the write: scopes to let it make changes. Full access alone does not enable MCP.

Create API key

Install with the key

Pass the key as an Authorization header, replacing YOUR_TOKEN.

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

{
  "mcpServers": {
    "xcloud": {
      "type": "http",
      "url": "https://app.xcloud.host/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Add to your Claude Desktop config, then restart the app.

{
  "mcpServers": {
    "xcloud": {
      "url": "https://app.xcloud.host/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Add to ~/.cursor/mcp.json.

URL:    https://app.xcloud.host/mcp
Header: Authorization: Bearer YOUR_TOKEN

Stdio-only client? Bridge with npx mcp-remote https://app.xcloud.host/mcp --header "Authorization: Bearer YOUR_TOKEN".

Too many tools for your client? Pick a profile or a toolset

Profiles

One endpoint, two shapes. Everything below is served from the same https://app.xcloud.host/mcp with the same token — only the tool list differs.

Flat (default) — every xCloud API operation is its own tool (servers_index, sites_ssl, …), plus xcloud_agent_search for finding the right one and the order to call them in, and xcloud_docs_search for answering a question from the xCloud documentation.
Compact (?profile=compact) — five tools: the two searches plus three executors split by what a call does (read, write, irreversible). Use this when your client caps how many tools a server may advertise — Cursor stops at 40 — or when you would rather not pay for ~150 tool descriptions on every session.

https://app.xcloud.host/mcp?profile=compact

An API key can carry mcp:profile:compact instead, for clients whose configuration has no room for a query string. https://app.xcloud.host/mcp/v2 still works and is the same compact surface.

Toolsets

A toolset is one area of xCloud — servers, sites, billing, wordpress-actions and so on. Narrowing to one or more shows the agent only those tools. Both search tools are always there, so the agent can still tell you what it cannot reach.

https://app.xcloud.host/mcp?toolsets=sites,servers

The full list with the number of tools in each is at https://app.xcloud.host/mcp/toolsets. An API key can also be limited to toolsets when you create it — tick them under MCP toolsets on the API tokens page. A key with none selected sees every tool, which is how every existing key behaves.

Toolsets narrow what the agent is shown, not what your key may do: the permissions on the key are what actually decide every call.

Troubleshooting

Symptom	Cause & fix
Client asks for a token	It doesn’t support browser sign-in. Use the API key path instead.
403 on connect	The approval was declined or granted read-only for a write action — reconnect and approve read & write. On the API-key path, the key lacks explicit `mcp:invoke`.
“Lacks the … ability”	The connection isn’t permitted that action. Reconnect with write access, or add the missing scope (e.g. `write:sites`) to your API key.
“Site not found”	The connection is scoped to a different team than the site. Switch teams in xCloud, then reconnect.
401 Unauthorized	Sign-in expired — reconnect. On the API-key path, the key is invalid or the `Authorization` header was mangled; check the single-quoting around the `\|`.
Client refuses to load all the tools	Some clients cap the tools per server (Cursor at 40). Connect with `?profile=compact`, or narrow to the areas you need with `?toolsets=…` — see Too many tools for your client?
A tool you expected isn’t listed	The key is limited to some MCP toolsets, or the URL carries `?toolsets=`. Ask `xcloud_agent_search` for the operation — it says what exists — then widen the key or drop the parameter.

Tip: if you’re using an API key, xCloud tokens contain a | — keep the single quotes so your shell doesn’t read it as a pipe.

API reference · Agent skills