> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents.labs.bandwidth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces and permissions

> Verify your selected workspace and understand how switching affects your connected clients.

Complete [client setup](https://docs.agents.labs.bandwidth.com/mcp/clients.md) first. MCP uses your account's selected workspace; REST API-key requests select their workspace with a request header.

## Verify workspace access

In your connected assistant, send this prompt:

```text theme={null}
Use bandwidth_agents to call get_current_workspace, then list_agents.
Show the workspace name and my agents' names and IDs without changing anything.
```

A successful tool result contains the agents you can access in your selected workspace. An empty list can be a successful response when the workspace has no agents. Use `get_current_workspace` to check the selection if the results are unexpected.

### Change workspace

1. Call `list_workspaces` to see the workspaces you belong to, their groups, and your role in each group.
2. Call `switch_workspace` with the desired group's `id` as `group_id`. Use the ID returned in `groups`, not `tenant_id` or the public workspace ID. If the name is ambiguous, choose the intended group before switching.
3. Check the returned workspace and group names, then call `list_agents` to get agent names, IDs, and lifecycle states. `list_workflows` is an equivalent name for the same directory. Both include agents that have never taken a call. Look up resource IDs again in the selected workspace before editing.

Any member, including a Viewer, can switch to a group they belong to. Switching does not grant additional permissions: creating or editing agents still requires Editor or higher in that group. Repeating a switch to the same group is safe; invalid IDs and inaccessible groups return a tool error without changing your selection.

> [!WARNING]
>
> Workspace selection is shared by your account. Switching through MCP also changes the selection used by subsequent requests from Agent Builder and every other MCP client signed in with the same account. The response reports `selection_scope: "account"`. Another client can change it between calls, so avoid working in different workspaces simultaneously under the same account. Refresh the UI to see its updated selection.

The server checks your current workspace membership and role for each tool call. You can also switch in Agent Builder before your next MCP request; you do not need to reconnect just to change workspace.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.