Manage Multiple xCloud Teams with One API Token or MCP Connection

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.

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	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.

Prerequisites

• An xCloud account that belongs to two or more teams.
• Permission to create API tokens or authorize an MCP client.
• The UUID of a granted team when you want to target it through the Public API.
• A secure credential store for the token. xCloud shows a newly created token only once.

How multi-team access works

Action	Public API	MCP
Use the default team	Omit X-Team-Id	Omit the optional team argument
Discover granted teams	GET /api/v1/teams	Call teams_index
Use another granted team	Send X-Team-Id: <team-uuid>	Pass the team UUID as team
Select an ungranted team	Request returns 403	Request is refused; there is no silent fallback

Every request runs against exactly one team. Existing single-team tokens continue to use their default team without a team selector.

Step 1: Open the API Tokens page

Sign in to xCloud, then go to Account → 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.

The current team is fixed as the token’s default team. Select each additional team the connection 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 through the Public API

Omit X-Team-Id to run the request against the token’s default team.

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 through the Public API

Pass the UUID returned by GET /teams in the X-Team-Id header.

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.

Step 7: Select a team through MCP

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 with an error, never silently swapped for the default. The server URL is:

https://app.xcloud.host/mcp

Then follow this sequence:

1. Ask the agent to list the granted teams with teams_index.
2. Identify the team UUID from the result.
3. Pass that UUID as the optional team argument on another xCloud tool.
4. Omit team when you want the default team.

Example prompt:

List the teams this xCloud connection can access. Then show the servers in Client North.

Expected result: The agent resolves the team through teams_index and supplies its UUID as the team argument for the server request. In practice you just name the team: “only for the Acme team”, “in Client North”.

Options and settings

Setting	What it controls	Recommendation
Default team	The team used when the request has no selector	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
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	Use a UUID returned by teams_index

Limits and security behavior

• A multi-team connection can access only its default team and explicitly granted additional teams.
• Selecting an ungranted or removed team returns 403; xCloud does not fall back to the default team.
• Team membership, roles, token scopes, and endpoint authorization still apply after team selection.
• Each request targets one team. A single request does not combine resources from several teams.
• Existing single-team tokens continue to work without X-Team-Id or an MCP team argument.

Verify the setup

Run these checks after creating the connection:

1. Call GET /api/v1/teams or teams_index 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 UUID and confirm it returns that team’s resources.
4. Try a UUID 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
Request uses the wrong team	The selector was omitted	Add X-Team-Id for API requests or team for MCP calls
MCP client cannot use a bearer token	mcp:invoke was not enabled	Create or update the connection with MCP access enabled
Team does not appear during token creation	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.
• Using a team name in X-Team-Id. The header requires the team UUID.
• 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.

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.
• 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.