# Workspaces — MCP

> Workspaces compose multiple MCP servers into a single gateway URL. Create, manage, and configure workspaces for personal use, teams, and per-project isolation.

A workspace is a named collection of MCP servers exposed through a single gateway URL. Every MCP server you add — hosted, proxied, or installed from the Hub — is organized into a workspace. Your AI client connects to one URL and gets access to all tools across all servers.

---

## Create a Workspace

```bash
aerostack workspace create "Engineering"
# -> Token: mwt_xxxxxxxx (shown once — save this)
```

Or create from the Admin dashboard: **Workspaces** > **New Workspace**.

---

## Gateway URL

Each workspace has a gateway URL:

```
https://gateway.aerostack.dev/ws/<workspace-slug>/sse
```

This is the single URL you add to your editor. All MCP servers in the workspace are accessible through it.

### Editor Configuration

Add the gateway URL to your editor's MCP config:

```json
{
  "mcpServers": {
    "engineering": {
      "url": "https://gateway.aerostack.dev/ws/engineering/sse",
      "headers": { "Authorization": "Bearer mwt_xxxxxxxx" }
    }
  }
}
```

**When you add or remove MCP servers from the workspace, your editor picks up the changes automatically.** No config edit needed after initial setup.

---

## Tool Namespacing

Tools from different MCP servers are namespaced by the server slug to avoid collisions:

```
github-mcp   ->  github-mcp__create_issue
                  github-mcp__list_pull_requests

slack-mcp    ->  slack-mcp__send_message
                 slack-mcp__create_channel

internal-api ->  internal-api__query_users
                 internal-api__create_user
```

Your AI client sees all tools as a flat list. The namespace prefix tells you which server each tool belongs to.

---

## Managing Workspaces

### List all workspaces

```bash
aerostack workspace list
#   client-acme  Acme Corp      1             3
```

The `*` indicates your active workspace.

### Switch active workspace

```bash
aerostack workspace use personal
# -> Active workspace set to: personal
```

The active workspace is the default target for `mcp install`, `mcp remove`, and other workspace operations.

### Delete a workspace

```bash
aerostack workspace delete client-acme
# -> Workspace deleted.
```

Deleting a workspace revokes all tokens and removes all MCP server associations. Secrets stored for MCP servers in this workspace are also deleted. This action cannot be undone.

---

## Workspace Isolation

- MCP servers installed in one workspace do not appear in others
- Secrets are scoped per MCP server per workspace
- Tokens are scoped to a single workspace
- Analytics are tracked per workspace

This means you can have the same MCP server (e.g., `github-mcp`) installed in multiple workspaces with different secrets:

```bash
# Work workspace uses the company GitHub token
aerostack secrets set github-mcp GITHUB_TOKEN "ghp_company_xxx" --workspace engineering

# Personal workspace uses your personal token
aerostack secrets set github-mcp GITHUB_TOKEN "ghp_personal_xxx" --workspace personal
```

---

## Recommended Setup

### Solo developer

```bash
# One workspace with everything
aerostack workspace create personal
aerostack mcp install @aerostack/github-mcp
aerostack mcp install @aerostack/slack-mcp
aerostack mcp install @aerostack/notion-mcp
```

### Small team (2-10 engineers)

```bash
# Shared workspace with team tokens
aerostack workspace create engineering
aerostack mcp install @aerostack/github-mcp
aerostack mcp install @aerostack/slack-mcp
aerostack mcp install internal-api

# Issue one token per member
aerostack workspace token create engineering --name "Alice"
aerostack workspace token create engineering --name "Bob"
```

### Enterprise (10+ engineers, multiple teams)

```bash
# Tiered workspaces by access level
aerostack workspace create eng-full       # Senior engineers: all tools
aerostack workspace create eng-standard   # Standard engineers: no deploy
aerostack workspace create eng-readonly   # Contractors: read-only tools

# Per-project workspaces for isolation
aerostack workspace create project-alpha
aerostack workspace create project-beta
```

### Agency / Consultancy

```bash
# Per-client workspaces (complete isolation)
aerostack workspace create client-acme
aerostack workspace create client-globex
aerostack workspace create client-initech
```

---

## Multiple Workspaces in One Editor

You can connect to multiple workspaces simultaneously:

```json
{
  "mcpServers": {
    "work": {
      "url": "https://gateway.aerostack.dev/ws/engineering/sse",
      "headers": { "Authorization": "Bearer mwt_work_xxx" }
    },
    "personal": {
      "url": "https://gateway.aerostack.dev/ws/personal/sse",
      "headers": { "Authorization": "Bearer mwt_personal_xxx" }
    }
  }
}
```

Tools from both workspaces are available to your AI client, each namespaced by their server slug.

---

## Next Steps

- [Team management](/mcp/team-management) — tokens, analytics, access control
- [Secrets and security](/mcp/secrets-security) — how secrets are scoped per workspace
- [Quick Start](/mcp/quick-start) — set up your first workspace