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

# Switch workspace

> MCP reference for switch_workspace.

Tool: `switch_workspace`. Requires **Viewer or higher** in the applicable workspace and a connected [OAuth session](https://docs.agents.labs.bandwidth.com/mcp/authentication.md).

Select a group returned by `list_workspaces`. This changes the account-wide selection used by the UI and all MCP clients. Repeating the same selection is safe; invalid or inaccessible IDs fail without switching.

Call `list_agents` after switching. Avoid parallel work across different workspaces under one account. Membership and roles are checked again for resource operations.

## Arguments

| Name | Type | Required | Defaults and limits |
| - | - | - | - |
| `group_id` | integer | Yes | exclusiveMinimum: `0` |

## Example arguments

Replace sample resource IDs with IDs returned in your selected workspace.

```json theme={null}
{
  "group_id": 32
}
```

## Result and errors

The schema below describes MCP `structuredContent`, including the `result` wrapper where present. Your client may also display a text representation. Read success flags and structured errors before continuing; transport success alone does not prove the operation succeeded. Authentication, missing membership, and insufficient role can fail before a tool result is produced. See [troubleshooting](https://docs.agents.labs.bandwidth.com/mcp/troubleshooting.md).

**Effect:** Changes state. **Retry:** Declared idempotent. Discovery annotations describe behavior; they do not grant permission or replace confirmation for consequential actions.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "group_id": {
>       "exclusiveMinimum": 0,
>       "type": "integer"
>     }
>   },
>   "required": [
>     "group_id"
>   ],
>   "type": "object"
> }
> ```

> [accordion] Result schema
>
> ```json theme={null}
> {
>   "properties": {
>     "group_id": {
>       "type": "integer"
>     },
>     "group_name": {
>       "anyOf": [
>         {
>           "type": "string"
>         },
>         {
>           "type": "null"
>         }
>       ]
>     },
>     "public_id": {
>       "anyOf": [
>         {
>           "type": "string"
>         },
>         {
>           "type": "null"
>         }
>       ]
>     },
>     "role": {
>       "type": "string"
>     },
>     "selection_scope": {
>       "const": "account",
>       "default": "account",
>       "type": "string"
>     },
>     "tenant_id": {
>       "anyOf": [
>         {
>           "type": "integer"
>         },
>         {
>           "type": "null"
>         }
>       ]
>     },
>     "tenant_name": {
>       "anyOf": [
>         {
>           "type": "string"
>         },
>         {
>           "type": "null"
>         }
>       ]
>     }
>   },
>   "required": [
>     "tenant_id",
>     "public_id",
>     "tenant_name",
>     "group_id",
>     "group_name",
>     "role"
>   ],
>   "type": "object"
> }
> ```


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