# Workspaces

> A Workspace is a single gateway URL that composes multiple MCP servers, skills, and functions into one endpoint any AI agent can call.

A Workspace is the core building block of Aerostack. It composes multiple MCP servers, skills, and functions behind a **single gateway URL**. Instead of configuring each tool separately, you create a workspace, add the tools you need, and connect with one URL and one bearer token.

Every AI client that speaks MCP -- Claude Desktop, Cursor, your own applications, Aerostack Bots -- connects to this single endpoint and gets access to everything.

---

## How It Works

```mermaid
flowchart TD
    A["Claude Desktop"] --> GW["Workspace Gateway\nsingle URL + bearer token"]
    B["Cursor"] --> GW
    C["Your App"] --> GW
    D["Aerostack Bot"] --> GW
    GW --> S1["Stripe MCP"]
    GW --> S2["GitHub MCP"]
    GW --> S3["Custom Function"]
    GW --> S4["Notion MCP"]

    style GW fill:#3b82f6,stroke:#2563eb,color:#fff
    style A fill:#1e293b,stroke:#6b7280,color:#fff
    style B fill:#1e293b,stroke:#6b7280,color:#fff
    style C fill:#1e293b,stroke:#6b7280,color:#fff
    style D fill:#1e293b,stroke:#6b7280,color:#fff
    style S1 fill:#1e293b,stroke:#6b7280,color:#fff
    style S2 fill:#1e293b,stroke:#6b7280,color:#fff
    style S3 fill:#1e293b,stroke:#6b7280,color:#fff
    style S4 fill:#1e293b,stroke:#6b7280,color:#fff
```

When a client calls `tools/list`, the gateway fans out to **all enabled servers in parallel**, merges the results, and returns a unified tool list. When a client calls `tools/call`, the gateway routes the request to the correct upstream server and returns the result. All of this happens behind one URL.

---

## Use Cases

### Unified AI Backend

Combine Stripe for payments, GitHub for code, Notion for docs, and your own custom functions into a single workspace. Your AI agent gets one connection with access to all of them.

### Multi-Service Orchestration

An LLM connected to your workspace can create a GitHub issue, update a Notion page, and send a Slack notification -- all in a single conversation, without reconfiguring anything.

### Bot Brain

Every Aerostack Bot connects to a workspace for its tool access. The workspace defines what the bot can do. Change the tools in the workspace, and the bot's capabilities change instantly.

### Team Collaboration

Invite team members to a shared workspace. Each member gets their own token with independent analytics and rate limits. Revoke access instantly when someone leaves.

### Connect from Any LLM Client

The gateway speaks standard MCP (JSON-RPC 2.0 over HTTP). Claude Desktop, Cursor, Windsurf, and any MCP-compatible client can connect using the gateway URL and a bearer token.

---

## Key Concepts

### Gateway URL

Each workspace gets a unique gateway URL:

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

This is a standard MCP endpoint. Authenticate with a workspace token (`mwt_` prefix) in the `Authorization` header.

  The gateway is also available at `https://api.aerostack.dev/api/gateway/ws/<workspace-slug>` if you prefer the API domain.

### Tool Namespacing

To prevent name collisions across servers, the gateway namespaces every tool:

```
{serverSlug}__{toolName}
```

For example, a GitHub server with slug `github` and a tool named `create_issue` becomes `github__create_issue`. When you call it, the gateway strips the prefix, routes to the correct server, and returns the result.

### Parallel Fan-Out

When a client calls `tools/list`, the gateway calls all enabled servers simultaneously and merges the results. A slow server does not block others -- each server has an independent timeout.

### Workspace Isolation

- Tools in one workspace do not appear in others
- Each workspace has its own tokens, secrets, and server configurations
- Workspaces are scoped to your account

---

## What You Can Add to a Workspace

| Type | Description |
|------|-------------|
| **Community MCP Servers** | Published servers from the Aerostack Hub marketplace |
| **External MCP Servers** | Your own MCP servers running anywhere (provide the URL) |
| **Skills** | Workflow-powered tools with triggers and automation |
| **Functions** | Community functions auto-wrapped as MCP tool endpoints |

You can add up to **50 servers** per workspace (varies by plan).

---

## What Connects to Workspaces

Everything in Aerostack that needs tool access connects through a workspace:

| Product | How It Connects |
|---------|----------------|
| **Bots** | Each bot is linked to a workspace via `workspace_id`. The bot's LLM uses workspace tools to answer questions and take actions. |
| **Agent Endpoints** | REST API agents powered by a workspace's tools |
| **Claude Desktop / Cursor** | Direct MCP connection via gateway URL + bearer token |
| **SDK Clients** | Programmatic access using the Aerostack SDK |

---

## Plan Limits

| Plan | Workspaces | Servers per Workspace | MCP Proxy Calls/mo |
|------|------------|----------------------|-------------------|
| Free | 3 | 5 | 5,000 |
| Starter | 10 | 15 | 50,000 |
| Pro | 50 | 50 | 500,000 |
| Business | 200 | 200 | 5,000,000 |
| Enterprise | Unlimited | Unlimited | Custom |

---

## Rate Limiting

The gateway enforces **120 requests per minute** per workspace token. Rate limits are per-token, not per-workspace -- if you need higher throughput, issue multiple tokens and distribute load.

  When rate-limited, the gateway returns HTTP 429. See [Connect via Gateway](/workspaces/gateway-url) for full error response details.

---

## Next Steps

- [Create a Workspace](/workspaces/create-workspace) -- set up your first workspace in minutes
- [Add Tools](/workspaces/add-tools) -- populate your workspace with MCP servers, skills, and functions
- [Connect via Gateway](/workspaces/gateway-url) -- connect Claude Desktop, Cursor, or any MCP client
- [Tokens](/workspaces/tokens) -- issue, manage, and revoke gateway tokens
- [Secrets](/workspaces/secrets) -- securely inject API keys into server calls
- [Team Members](/workspaces/members) -- invite collaborators and manage access
- [Analytics](/workspaces/analytics) -- track tool usage and performance