Skip to main content
Complete client setup 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:
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.
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.