Skip to content
Aerostack v1.0-beta

Workspaces — MCP

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

Section titled “Create a Workspace”
Terminal window
aerostack workspace create "Engineering"
# -> Workspace created.
# -> Gateway URL: https://gateway.aerostack.dev/ws/engineering/sse
# -> Token: mwt_xxxxxxxx (shown once — save this)

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

Gateway URL

Section titled “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

Section titled “Editor Configuration”

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

{
  "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

Section titled “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

Section titled “Managing Workspaces”

List all workspaces

Section titled “List all workspaces”
Terminal window
aerostack workspace list
# SLUG           NAME           MCP SERVERS   TOKENS
# * engineering  Engineering    4             8
#   personal     Personal       2             1
#   client-acme  Acme Corp      1             3

The * indicates your active workspace.

Switch active workspace

Section titled “Switch active workspace”
Terminal window
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

Section titled “Delete a workspace”
Terminal window
aerostack workspace delete client-acme
# -> This will revoke all 3 tokens and remove 1 MCP server.
# -> Confirm? [y/N] y
# -> Workspace deleted.

Workspace Isolation

Section titled “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:

Terminal window
# 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
Section titled “Recommended Setup”

Solo developer

Section titled “Solo developer”
Terminal window
# 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)

Section titled “Small team (2-10 engineers)”
Terminal window
# 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)

Section titled “Enterprise (10+ engineers, multiple teams)”
Terminal window
# 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

Section titled “Agency / Consultancy”
Terminal window
# 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

Section titled “Multiple Workspaces in One Editor”

You can connect to multiple workspaces simultaneously:

{
  "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

Section titled “Next Steps”