Connecting to Multiple Workspaces

Each MCP connection is scoped to one workspace, and how to run several at once.

Connecting to multiple workspaces

Each MCP connection is scoped to a single workspace: the one you selected during the OAuth login flow. To work across multiple workspaces simultaneously, add Catio as a separate named server for each workspace.

Example: two workspaces in Claude Code

claude mcp add --transport http catio-prod https://mcp.catio.tech/mcp
claude mcp add --transport http catio-staging https://mcp.catio.tech/mcp

Then authenticate each one separately via /mcp → select the server → Login. Each login flow lets you pick a different workspace.

Example: two workspaces in Cursor

{
  "mcpServers": {
    "catio-prod": {
      "url": "https://mcp.catio.tech/mcp"
    },
    "catio-staging": {
      "url": "https://mcp.catio.tech/mcp"
    }
  }
}

Each server entry authenticates and maintains its own session independently, so each can be logged into a different workspace.

Multiple workspaces with API keys

With API keys there is a second way to work across workspaces:

  • One unbound key: leave the workspace list empty and the key reaches every workspace you can access. Pass workspace_id on each call to say which workspace the call works in.
  • One key per workspace: create a key bound to a specific workspace, and add a separate server entry for each.

Keys do not use the workspace selection from the OAuth login flow. See API Keys.


Switching workspaces

To change which workspace a server is connected to, clear its authentication and log in again:

  • Claude Code / OpenCode: /mcp → select the server → Clear authentication → Login
  • Other clients: remove and re-add the server entry, then re-authenticate

Did this page help you?