How to Get a Fleet Overview of All Servers and Sites with the xCloud Public API and MCP

The fleet overview returns every server and site you can access in your xCloud team in one request, with each server’s stored status, its usage warnings and status counts for the whole team. Call it as GET /api/v1/overview from a script, or ask an AI agent to run the overview_show MCP tool. It is the fastest way to build a fleet home page, a morning health check or a “which servers need attention” report without calling each server’s detail endpoint.

The overview is new in xCloud v2.9.6.1.

What the overview returns

The response has four parts. All values come from data xCloud has already stored; the request does not contact your servers.

Field	What it holds
servers	Up to 500 servers: uuid, name, provider, type (the server stack), status, state, is_connected and usage
sites	Up to 500 sites: uuid, name, server_uuid, type, status and php_version
counts	The number of servers and of sites per stored status, for every resource you can access, before the 500 cap
truncation	For servers and for sites: whether the list was cut (truncated), the limit (500) and the next_action to read the rest

Each server’s usage object carries the same warnings the xCloud dashboard shows:

Usage field	Meaning
cpu_percent, ram_percent, disk_percent	The last stored readings, or null when xCloud has no disk snapshot for the server
cpu_high	CPU use is above 80%
ram_low	Less than 10% of RAM is available
disk_low	A watched filesystem (/var/www, /var/lib/mysql or /) has less than 5 GB free
disk_critical	A watched filesystem has less than 1 GB free

state is the server’s summary state as the dashboard shows it: Initial, Processing, Success, Warning, Disconnected or Error, or null when none applies.

Prerequisites

• An xCloud API token with both read:servers and read:sites. See How to Access the xCloud API to create one.
• For MCP, the token or connection must also allow MCP (mcp:invoke). An OAuth connection from an MCP client works too. See How to Connect xCloud MCP to Your AI Agent.
• The Team Admin or Server Admin role in the team. A Site Admin cannot read the overview, because it includes server summaries.

The overview is read-only. A token with no write permissions is enough, and is the safer choice for dashboards and reports.

Step 1: Call the overview endpoint

Send a GET request with your token. Store the token in an environment variable instead of pasting it into the command.

export XCLOUD_TOKEN='xc_live_xxxxxxxxxxxx'

curl 'https://app.xcloud.host/api/v1/overview' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json'

Expected result: a 200 response with the servers, sites, counts and truncation for the token’s default team. A shortened example:

{
  "success": true,
  "message": "Success",
  "data": {
    "servers": [
      {
        "uuid": "9a1f0c2e-4b7d-4e8a-9c3f-1d2e3f4a5b6c",
        "name": "docs-demo",
        "provider": "hetzner",
        "type": "nginx",
        "status": "provisioned",
        "state": "Success",
        "is_connected": true,
        "usage": {
          "cpu_percent": 12.5,
          "ram_percent": 44.1,
          "disk_percent": 93,
          "cpu_high": false,
          "ram_low": false,
          "disk_low": false,
          "disk_critical": false
        }
      }
    ],
    "sites": [
      {
        "uuid": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
        "name": "example.com",
        "server_uuid": "9a1f0c2e-4b7d-4e8a-9c3f-1d2e3f4a5b6c",
        "type": "wordpress",
        "status": "provisioned",
        "php_version": "8.3"
      }
    ],
    "counts": {
      "servers": { "provisioned": 1, "provisioning": 0, "error": 0 },
      "sites": { "provisioned": 1, "provisioning": 0, "provisioning_failed": 0 }
    },
    "truncation": {
      "servers": { "truncated": false, "limit": 500, "next_action": null },
      "sites": { "truncated": false, "limit": 500, "next_action": null }
    }
  }
}

counts lists every stored status for servers and for sites, including the ones at 0, so a client can show a fixed set of tiles. The example above is shortened.

To read another granted team, add the X-Team-Id header with that team’s UUID from GET /api/v1/teams. See Multi-Team API Tokens and MCP Access.

Step 2: Find the servers that need attention

Filter the response for servers with a warning flag or a disconnected agent. This example uses jq:

curl -s 'https://app.xcloud.host/api/v1/overview' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json' \
  | jq '.data.servers[]
        | select(.is_connected == false or .usage.cpu_high or .usage.ram_low or .usage.disk_low)
        | {name, state, usage}'

Expected result: one JSON object per server that needs a look, or no output when every server is healthy. A server with disk_critical: true is about to fail writes; free disk space on it first.

The usage figures are the last stored readings, not a live measurement. To see the current values and history for one server, open it in the dashboard as described in How To Monitor Server Resource Usage with xCloud. For the same fleet view in the dashboard, see xCloud Monitoring.

Step 3: Read the rest when a list is truncated

Each list holds at most 500 entries, in the order the servers or sites were created. When a team has more, the counts stay complete and truncation tells you where the rest is:

"truncation": {
  "servers": { "truncated": false, "limit": 500, "next_action": null },
  "sites": { "truncated": true, "limit": 500, "next_action": "sites.index" }
}

next_action names the paginated list operation: servers.index is GET /api/v1/servers, and sites.index is GET /api/v1/sites. Both take page and per_page (up to 100):

curl 'https://app.xcloud.host/api/v1/sites?page=1&per_page=100' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json'

Expected result: the first 100 sites. Increase page until you have read every site. Use the totals in counts to check that your client has them all.

Step 4: Ask an AI agent for the overview over MCP

In an MCP client connected to xCloud, ask in plain language:

Give me an overview of all my xCloud servers and sites. List any server that is
disconnected or has a CPU, RAM or disk warning, and tell me how many sites are
not provisioned.

The agent runs the overview_show tool, which calls the same endpoint and returns the same data. On the compact MCP profile, the agent finds the overview.show operation with search and runs it through xcloud_execute_read, which changes nothing.

Expected result: a summary of your servers and sites, with the servers that need attention named. To ask about another granted team, name the team in the prompt.

If a list was truncated, the agent can follow next_action and page through servers.index or sites.index the same way.

What the overview leaves out

• System sites, such as a server’s phpMyAdmin site, are not in sites or in counts.
• Resources you cannot access. A Server Admin with access to selected servers sees only those servers and their sites, and the counts cover only them. Other teams never appear.
• Secrets and addresses. Server passwords and public IPs are not in the response. Use the server detail endpoints for connection details.
• Live metrics. No command runs on your servers. A server with no stored disk snapshot shows null usage and false warning flags.

Troubleshooting

Response	Cause	Fix
401	No bearer token, or the token was revoked	Send Authorization: Bearer <token> with an active token
403	The token is missing read:servers or read:sites	Create a token with both permissions. Tokens cannot be edited
403 with both permissions	Your team role is Site Admin	Ask the team owner for the Server Admin or Team Admin role
403 with X-Team-Id	The team is not granted to the token	Call GET /api/v1/teams and use a returned UUID
A server is missing	You do not have access to that server, or the list was truncated	Check counts and truncation, then your server access in the team
All usage values are null	xCloud has no disk snapshot for the server yet	Wait for monitoring to store one, or check the server’s connection

Frequently asked questions

Why does GET /api/v1/overview return 403 when my token can list servers?

The overview needs both read:servers and read:sites on the token, and your team role must be Team Admin or Server Admin. A token with only one of the two permissions, or a Site Admin, receives 403.

Does the overview contact my servers or refresh their metrics?

No. It reads the status and the last monitoring snapshot xCloud has already stored, the same data the dashboard shows. It runs no command on your servers.

What happens when I have more than 500 servers or sites?

Each list stops at 500 entries in creation order, but the counts still cover everything you can access. truncation.servers or truncation.sites then reports truncated as true and names servers.index or sites.index, the paginated list to read the rest from.

Why are a server’s usage values null?

xCloud has no disk snapshot for that server yet, so every usage figure is unknown. The percentages are null and the warning flags are false until monitoring stores a snapshot.

Next steps

• Read the full request and response format in the xCloud Public API reference, and authentication and rate limits in the xCloud API documentation overview.
• Deploy from the same token with Deploy Git Projects with the xCloud Public API and MCP.

If you run into any issues with the fleet overview, feel free to reach out to our support team for help.