Workspaces
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
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 |
| Smart Webhooks | AI webhook processors that use workspace tools to handle incoming events |
| 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 for full error response details.
Next Steps
- Create a Workspace — set up your first workspace in minutes
- Add Tools — populate your workspace with MCP servers, skills, and functions
- Connect via Gateway — connect Claude Desktop, Cursor, or any MCP client
- Tokens — issue, manage, and revoke gateway tokens
- Secrets — securely inject API keys into server calls
- Team Members — invite collaborators and manage access
- Analytics — track tool usage and performance