Manage xCloud API Tokens and MCP Connections Across Multiple Teams

One connection. Every team you choose. Since xCloud v2.8.8, one API token or one MCP connection can be granted access to the teams you select, keep one of them as its default, and switch to another granted team on any single request. You authorize once and never reconnect to change teams.

This is for agencies, developers and operators who run more than one xCloud team: several client workspaces, a staging team and a production team, or one automation that has to see all of them.

This guide also covers day-to-day management of xCloud API tokens and MCP connections: limiting what an AI agent can do, checking when a token was last used, and revoking a token or connected app.

What changed in v2.8.8

	Before	Now
Teams per token or MCP connection	Exactly one	The default team plus every additional team you grant
Working across teams	A separate token per team, or authorizing the MCP client again for each one	One token or one connection, switched per request
Selecting a team on the API	Not possible	Send X-Team-Id: <team-uuid>
Selecting a team on MCP	Not possible	Name the team; the agent passes the optional team argument
A team you did not grant	Not reachable	Still not reachable: the request is refused with 403, never silently redirected to the default
Existing single-team tokens	Work	Still work, unchanged

The connection never receives blanket access. The teams you grant define its boundary, and each team’s existing roles and permissions still apply on top. See team roles and permissions in xCloud for what a role allows. The release notes are in the v2.8.8 changelog.

Pick your path

The two paths share one authorization model but different mechanics, so this guide keeps them apart. Read the one you use; the boundary rules at the end apply to both.

	MCP connection	Public API token
You are	Talking to an AI assistant (Claude, Cursor, Codex, Hermes and others)	Writing scripts, CI jobs or an integration that calls app.xcloud.host/api/v1
You grant teams	On the browser approval screen when you connect	On the API Tokens page when you create the token
You pick a team per request	By naming it in the prompt; the agent passes the team argument	With the X-Team-Id header
You discover granted teams	“List the teams this connection can access” (teams_index)	GET /api/v1/teams
Jump to	Path A: MCP	Path B: Public API

An MCP client that signs in with an API key instead of the browser gets its teams from the token, so follow Path B to create the token and Path A to use the teams.

Prerequisites

• An xCloud account that belongs to two or more teams.
• Permission to authorize an MCP client or create API tokens. The API Tokens page is not shown inside white-label (reseller) portals.
• For the API path: the UUID of a granted team when you want to target it, and a secure credential store for the token. xCloud shows a newly created token only once.

Path A: One MCP connection for several teams

Step 1: Tick the teams when you authorize

Connect your MCP client as described in How to Connect xCloud MCP to Your AI Agent. When you authorize in the browser, the approval screen lists your teams: the current team is always included, and you tick each additional team the connection may act on. Then choose Full access or Read-only and select Authorize.

Expected result: The connection is granted exactly the teams you ticked. A team you did not tick is refused, never silently swapped for the default. To add a team later, reconnect and tick it.

Step 2: Ask which teams it can see

List the teams this xCloud connection can access.

Expected result: The agent calls teams_index and answers with each granted team’s name, your role in it, and which one is the default.

Step 3: Name the team in the prompt

You never handle a UUID on this path. Say the team the way you would to a colleague, and the agent passes that team’s UUID as the optional team argument on the tool call. Omit the team and the request runs on the default.

Show the servers in Client North.

Only on the Acme team: which sites have pending WordPress updates?

List the teams this connection can access, then take the vulnerability count for every site on each of them and put it in one table, team by team.

Expected result: Each tool call runs against exactly one team. Ask for a team the connection was not granted and the agent gets a refusal, not the default team’s data. If a site “is not found”, the usual cause is that its team was not ticked; see troubleshooting.

Path B: One API token for several teams

Step 1: Open the API Tokens page

Sign in to xCloud, then go to Settings → Developers → API Tokens and select Create New Token.

Expected result: The token form opens with token name, permissions, MCP access, and team-selection controls.

Step 2: Choose permissions and grant teams

Enter a descriptive token name. Select only the API permissions the integration needs. Enable mcp:invoke separately if an AI agent will use this bearer token over MCP, and optionally pick MCP toolsets to show the agent only some areas of xCloud.

The current team is fixed as the token’s default team. Select each additional team the token may access.

Expected result: The current team remains selected as the default, while additional teams can be enabled individually.

Security note: Full API access does not automatically include mcp:invoke. MCP access is a separate, revocable permission.

Step 3: Create and store the token

Select Create Token, copy the generated value, and store it in your secret manager. Do not put the token in source control, screenshots, logs, or shared messages.

After creation, the API Tokens table shows the default team with a star and lists the additional teams granted to the token.

Expected result: The token row shows its permissions and teams. In the example, Acme Operations is the default team and Client North is an additional granted team.

Step 4: List the teams the token can access

Call the teams endpoint before targeting a non-default team. The response includes each granted team’s UUID, role, and default status.

curl 'https://app.xcloud.host/api/v1/teams' \
  --header 'Authorization: Bearer xc_live_xxxxxxxxxxxx' \
  --header 'Accept: application/json'

Example response:

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Acme Operations",
      "role": "owner",
      "is_default": true
    },
    {
      "uuid": "b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Client North",
      "role": "admin",
      "is_default": false
    }
  ]
}

Expected result: The response lists only the teams granted to this token.

Step 5: Use the default team

Omit X-Team-Id to run the request against the token’s default team, exactly as single-team tokens always have.

curl 'https://app.xcloud.host/api/v1/servers' \
  --header 'Authorization: Bearer xc_live_xxxxxxxxxxxx' \
  --header 'Accept: application/json'

Expected result: xCloud returns resources from the default team, subject to the token’s scopes and the user’s role.

Step 6: Switch to another granted team

Pass the UUID returned by GET /teams in the X-Team-Id header. The header takes the UUID, never the team name.

curl 'https://app.xcloud.host/api/v1/servers' \
  --header 'Authorization: Bearer xc_live_xxxxxxxxxxxx' \
  --header 'Accept: application/json' \
  --header 'X-Team-Id: b2c3d4-e5f6-7890-abcd-ef1234567890'

Expected result: The same token runs the request against the selected granted team. You do not need to create another token or reconnect the integration. A UUID that was not granted returns 403.

Control what AI agents can do with an API token

An AI agent that uses an API token can only do what you allowed on that token. Three settings on the token form decide it, and they work together rather than replacing each other.

Setting	What it controls	What it does not do
API permissions (scopes)	Which Public API operations the token may call, such as read:servers or write:sites	They do not let the token connect to an MCP client
mcp:invoke	Whether an AI agent may use the token over MCP at all	It grants no operations of its own
MCP toolsets	Which xCloud tools the agent sees in its tool list	They are not a permission boundary

On top of all three, each team’s roles and permissions still apply, as described in the boundary rules.

mcp:invoke opens MCP, the other permissions decide what the agent can do

mcp:invoke is the checkbox labelled allow AI agents to use this token. It is required to connect the token to an MCP client and is not included in Full Access, so a Full Access token cannot be used by an agent unless you also tick it.

The agent can only call operations the token’s API permissions allow. For example, a token with read:sites and mcp:invoke lets an agent list and inspect sites but refuses any change to them. Because mcp:invoke grants nothing by itself, xCloud does not let you create a token with only mcp:invoke: the form asks you to select at least one API permission for MCP access to be usable.

Narrow the tool list with MCP toolsets

MCP toolsets appear once you tick mcp:invoke. Each toolset is one area of the xCloud API, shown with its name and how many operations it holds. Select none and the agent sees every tool, which is the default. Select one or more and the agent sees only those areas; search stays available either way.

Toolsets are useful for MCP clients that limit how many tools one server may list, and for keeping an agent focused on one job. They shorten the list the agent sees but are not a security control: every call is still checked against the token’s API permissions and team roles. To stop an agent from making changes, remove the write: permissions instead.

For clients such as Cursor that cap the tool count, tick Compact tool surface (4 tools instead of ~150). The agent then searches for an operation and runs it through a small set of executor tools.

Monitor and revoke API tokens and MCP connections

You manage both kinds of access on Settings → Developers → API Tokens. API tokens appear in the token table; apps and AI clients that signed in through the browser (OAuth) appear under Connected apps. A connected app does not need an API token.

Check when an API token was last used

The token table has a Last Used column with the date and time of the token’s most recent authenticated request, for example 2026-10-19 09:42. A token that has never been used shows Never. The table also shows each token’s permissions, teams and creation date.

Use Last Used to find tokens that nothing uses any more, or a token that is still active after the integration it belonged to was retired. Revoke both. Each xCloud user can hold up to 10 API tokens, so removing unused ones also frees space for new ones.

Connected apps shows each app’s name, the teams it can act on, its scopes, how many active authorizations it has, and the date it was authorized. It does not show a last-used time.

Revoke an API token

Select the delete icon on the token’s row, then confirm with Yes, revoke it.

Expected result: xCloud shows Token revoked successfully. Every script, CI job or MCP client that used the token stops working at its next request. Revoking cannot be undone, and a token cannot be edited after it is created, so to change a token’s permissions or teams, create a new token and revoke the old one.

Revoke a connected app (MCP connection)

Under Connected apps, select the delete icon on the app’s row, then confirm with Yes, revoke it.

Expected result: xCloud shows MCP connection revoked. The app loses access immediately. Revoking removes every active authorization of that app at once, for example the same client signed in on two computers. To use it again, connect the MCP client and approve the browser authorization screen again.

	Revoke an API token	Revoke a connected app
What it removes	One bearer token	Every active OAuth authorization of one app or AI client
Who stops working	Anything that sends that token: scripts, CI jobs, MCP clients signed in with the token	That app or AI client on every device where it is signed in
Other access	Other tokens and connected apps keep working	API tokens and other connected apps keep working
To restore access	Create a new token and update the integration	Connect the client and approve it in the browser again

Manage tokens through the Public API

Integrations can manage tokens too. GET /api/v1/user/tokens lists the API tokens in the current team, including each token’s last_used_at, and DELETE /api/v1/user/tokens/{tokenUuid} revokes one. They need the read:tokens and write:tokens permissions; no other permission includes them, but Full Access does. See the xCloud Public API reference for the full request and response format, and the xCloud API documentation overview for authentication and rate limits.

What API token management does not include yet

xCloud does not offer the following today:

• Activity log. No dashboard page lists the requests or MCP actions each token or connected app made. Last Used is the only usage signal.
• Token expiry. A token stays valid until you revoke it.
• IP restrictions. A token works from any IP address.

Until these exist, use narrow API permissions, grant only the teams an integration needs, check Last Used regularly, and revoke anything you no longer use.

The boundary rules, shared by both paths

Rule	What it means
Explicit grants only	A connection or token can reach its default team plus the teams you explicitly granted. Nothing else, ever.
One team per request	Every request runs against exactly one team. A single call never combines resources from several teams; ask the agent for one team at a time, or loop over teams in your script.
Roles and scopes still apply	Selecting a team changes the request context. It does not bypass that team’s roles, the token’s scopes, or endpoint permissions.
No silent fallback	Selecting an ungranted or removed team returns 403 (API) or a refusal (MCP). xCloud never redirects to the default team.
Default team	Fixed when you connect or create the token: the team you were in at the time. Create the token while the intended default is current.
Existing tokens	Single-team tokens keep working unchanged, on their default team, with no selector needed.
Revoke	Tokens and connected apps are both listed on the API Tokens page and revoked separately. See revoking a token versus a connected app.

Options and settings

Setting	What it controls	Recommendation
Default team	The team used when the request has no selector	Connect or create the token while the intended default team is current
Additional teams	The only other teams the connection may select	Grant only the teams the integration needs
API scopes	Which Public API operations the token can perform	Prefer the narrowest read/write scopes that complete the task
mcp:invoke	Whether an AI agent may use the bearer token over MCP	Enable only for tokens intended for MCP clients
MCP toolsets	Which areas of xCloud the agent sees in its tool list	Optional; select the areas the agent’s job needs
X-Team-Id	Team selection for one Public API request	Use a UUID returned by GET /teams
team argument	Team selection for one MCP tool call	Let the agent fill it from teams_index; you just name the team

Verify the setup

Run these checks after creating the connection or token:

1. Call GET /api/v1/teams or ask the agent to list its teams, and confirm only the intended teams appear.
2. Make one request without a team selector and confirm it returns the default team’s resources.
3. Make one request with a granted team, by UUID or by name, and confirm it returns that team’s resources.
4. Try a team that was not granted and confirm xCloud refuses it with 403.
5. Confirm a role-limited account still cannot perform an operation its role does not allow.

Troubleshooting

Symptom	Likely cause	Fix
403 after adding X-Team-Id	The team was not granted, the grant was removed, or the user no longer belongs to the team	Call GET /teams, use a returned UUID, and review the token’s team grants
The agent says a site or server “is not found”	The site belongs to a team this connection was not ticked for	Ask the agent to list its teams; reconnect and tick the missing team
Request uses the wrong team	The selector was omitted, or the prompt did not name the team	Add X-Team-Id for API requests, or say the team in the prompt
MCP client cannot use a bearer token	mcp:invoke was not enabled on the token	Create a new token with mcp:invoke enabled, then revoke the old one. Tokens cannot be edited
“Select at least one API permission for MCP access to be usable.”	Only mcp:invoke (and toolsets) were selected	Add the API permissions the agent needs, such as read:servers
“Maximum 10 API tokens allowed.”	Your account already has 10 API tokens	Check Last Used and revoke a token you no longer need
The agent cannot find a tool it used before	The token has MCP toolsets that leave that area out	Create a token with the needed toolset, or with no toolsets selected
Team does not appear during token creation or authorization	The account cannot grant that team in the current context	Switch to the correct xCloud context and confirm team membership
Operation is denied on a granted team	The token scope or the user’s team role does not allow it	Grant the required token scope or use an appropriately authorized team member

Common mistakes

• Treating “Full Access” as permission for MCP. mcp:invoke remains separate.
• Treating MCP toolsets as a security limit. They only shorten the agent’s tool list; API permissions decide what it can do.
• Leaving old tokens in place. A token never expires on its own, so revoke tokens whose Last Used shows they are no longer needed.
• Using a team name in X-Team-Id. The header requires the team UUID. (Naming the team is the MCP way, not the API way.)
• Assuming a denied team silently falls back to the default. xCloud returns 403 instead.
• Granting every available team when an integration needs only one client workspace.
• Logging the token while debugging. Use the redacted placeholder xc_live_xxxxxxxxxxxx in examples.

Frequently asked questions

Does one token automatically access every team in my account?

No. The token can access its default team plus the additional teams you explicitly grant. Nothing else.

What happens when I omit the team selector?

The request runs against the token’s or connection’s default team, exactly as single-team tokens always have.

Can the same connection switch teams for each request?

Yes. The Public API accepts the X-Team-Id header, and MCP tools accept the optional team argument. No new token, no reconnecting.

Do team roles still apply?

Yes. Selecting a team changes the request context; it does not bypass that team’s roles, the token’s scopes, or endpoint permissions.

Do existing single-team integrations need changes?

No. They keep using their default team whenever no team selector is provided.

How do I see when an xCloud API token was last used?

Open Settings → Developers → API Tokens. The Last Used column shows the date and time of each token’s most recent authenticated request, or Never if it has not been used.

What is the difference between revoking an API token and revoking an MCP connection?

Revoking an API token disables that bearer token for every script, CI job or MCP client that uses it. Revoking a connected app removes every active OAuth authorization of that app or AI client, so it must sign in and be approved again to reconnect.

Does Full Access let an AI agent use my token over MCP?

No. MCP needs the separate mcp:invoke permission, and the agent can still only do what the token’s other API permissions allow. A token cannot be created with mcp:invoke alone.

Does xCloud have an activity log, expiry date or IP allowlist for API tokens?

Not yet. xCloud shows each token’s last-used time and lets you revoke tokens and connected apps at any time, but it does not show a per-token activity log, set token expiry dates, or restrict tokens to IP addresses.

Next steps

• Review the xCloud Public API reference and how to access the xCloud API.
• Connect an MCP client with the xCloud MCP setup guide, then see what you can ask xCloud MCP to do for prompts, including the multi-team recipe.
• Check each granted team at a glance with the fleet overview (GET /api/v1/overview with X-Team-Id, or overview_show over MCP).
• Start with read-only scopes, verify default and non-default team behavior, then add write access only where the workflow requires it.

If you run into any issues with multi-team access, feel free to reach out to our support team for help.