@aerostack/gateway

Connect any MCP client (Claude Code, Claude Desktop, Cline, Cursor, Goose, Windsurf, OpenClaw, and more) to an Aerostack Workspace — one URL, all your tools, with built-in human approval gates.

Why?

Many MCP clients only support stdio transport. Aerostack Workspaces use HTTP. This bridge connects them — no code required.

Instead of configuring dozens of separate MCP servers in your AI tool, point at one Aerostack Workspace and get:

• All tools in one place — composed from multiple MCP servers
• Centralized OAuth — 27+ providers managed by Aerostack, not your agent
• Human approval gates — sensitive tools require your approval before executing
• Local Guardian — approval gates for local operations (file delete, shell, git push, deploy)
• Agent Chat — message your agent from the dashboard with full conversation context
• Per-tool permissions — workspace tokens scope exactly which tools are accessible
• Usage tracking & audit — every tool call logged and metered

Quick Start

1. Get a workspace token

In your Aerostack Admin Dashboard, open your workspace and click Connect. Copy the workspace URL and token.

Your workspace URL looks like: https://mcp.aerostack.dev/ws/your-workspace

2. Configure your AI tool

First, install the gateway globally:

npm install -g @aerostack/gateway

Claude Code — run in your terminal:

claude mcp add aerostack -- aerostack-gateway \
  --env AEROSTACK_WORKSPACE_URL=https://mcp.aerostack.dev/ws/your-workspace \
  --env AEROSTACK_TOKEN=mwt_your_token_here

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "aerostack": {
      "command": "aerostack-gateway",
      "env": {
        "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-workspace",
        "AEROSTACK_TOKEN": "mwt_your_token_here"
      }
    }
  }
}

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aerostack": {
      "command": "aerostack-gateway",
      "env": {
        "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-workspace",
        "AEROSTACK_TOKEN": "mwt_your_token_here"
      }
    }
  }
}

OpenClaw — add the MCP server:

openclaw mcp set aerostack '{
  "command": "aerostack-gateway",
  "env": {
    "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-workspace",
    "AEROSTACK_TOKEN": "mwt_your_token_here"
  }
}'

Then restart the gateway:

openclaw gateway restart

Cline (VS Code) — add to VS Code settings under cline.mcpServers:

{
  "aerostack": {
    "command": "aerostack-gateway",
    "env": {
      "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-workspace",
      "AEROSTACK_TOKEN": "mwt_your_token_here"
    }
  }
}

Cursor / Goose / HTTP-native clients — use the workspace URL directly (no bridge needed):

URL:   https://mcp.aerostack.dev/ws/your-workspace
Token: mwt_your_token_here  (Authorization: Bearer header)

3. Verify your connection

Run the built-in diagnostic to verify everything works end-to-end:

AEROSTACK_WORKSPACE_URL="https://mcp.aerostack.dev/ws/your-workspace" \
AEROSTACK_TOKEN="mwt_your_token_here" \
aerostack-gateway --check

You should see:

  Aerostack Connection Check

  ✅ Workspace URL reachable    (https://mcp.aerostack.dev/ws/your-workspace)
  ✅ Token valid                (My Token, role: editor)
  ✅ Workspace connected        ("my-workspace")
  ✅ Tools available             (14 tools)
  ✅ Dashboard registration     (bridge visible in admin)

  All checks passed. Your agent is connected.
  Dashboard: https://app.aerostack.dev

If any step fails, the output tells you exactly what to fix.

4. Use it

You: Create a GitHub issue for the login bug
AI:  [calls github__create_issue via Aerostack workspace]

Tools are namespaced as {server}__{tool} (e.g., github__create_issue, slack__send_message).

Troubleshooting

Step-by-step debug:

# 1. Can the gateway reach your workspace?
aerostack-gateway --check

# 2. If using OpenClaw, is the gateway running?
openclaw gateway status

# 3. Is the MCP server configured?
openclaw mcp show aerostack

# 4. Start the gateway if not running
openclaw gateway start

# 5. Run OpenClaw's built-in diagnostics
openclaw doctor

Common issues:

How It Works

Your AI tool (stdio) → @aerostack/gateway → HTTPS → Aerostack Workspace
                                                          ↓
                                             ┌────────────────────────┐
                                             │ Fan-out to MCP servers │
                                             │ GitHub, Slack, Gmail,  │
                                             │ custom Workers, etc.   │
                                             └────────────────────────┘

The bridge:

1. Starts as a stdio MCP server (what your AI tool expects)
2. Forwards all JSON-RPC requests to your workspace over HTTPS
3. Handles SSE streaming responses transparently
4. Manages the approval gate flow automatically
5. Maintains conversation history for agent chat context

Approval Gates

When your workspace has approval rules configured, the bridge handles them transparently:

AI calls dangerous_tool
  → Bridge forwards to workspace
  → Workspace returns "needs approval" (-32050)
  → Bridge opens WebSocket to approval gate (instant push)
  → You approve/reject in dashboard or mobile app
  → Bridge receives decision instantly via WebSocket
  → Returns result on approval, error on rejection

Resolution is instant via WebSocket — no polling. A 30s safety-net poll runs in parallel only as a fallback if WebSocket drops.

Your AI agent sees either a successful result or a clear error — no special handling needed.

Local Guardian

Approval gates for local operations — file deletion, destructive shell commands, git push, deploys. The agent asks for approval before acting on your machine.

The bridge injects an aerostack__local_guardian tool. When the LLM is about to perform a risky local operation, it calls this tool first. You get a push notification and can approve or reject from the dashboard or your phone.

Agent wants to: rm -rf ./old-config/
  → Agent calls aerostack__local_guardian
  → You get push notification on your phone
  → Tap Approve or Reject
  → Agent proceeds or stops

Configuration

CLI Flags

Supported MCP Methods

Requirements

• Node.js 18+
• An Aerostack account with a configured workspace
• A workspace token (mwt_...)

Links

• Aerostack Docs
• Aerostack Admin
• MCP Specification

License

MIT