@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

Claude Code — run in your terminal:

claude mcp add aerostack -- npx -y @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": "npx",
      "args": ["-y", "@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": "npx",
      "args": ["-y", "@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": "npx",
  "args": ["-y", "@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

Note: OpenClaw loads MCP servers when a session starts. Send a message via Telegram (or another connected channel) to initialize the tools. After the first message, tools are available for all sessions.

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

{
  "aerostack": {
    "command": "npx",
    "args": ["-y", "@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 check to make sure everything is working:

AEROSTACK_WORKSPACE_URL="https://mcp.aerostack.dev/ws/your-workspace" \
AEROSTACK_TOKEN="mwt_your_token_here" \
npx @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

| Problem | Solution | |---------|----------| | npx hangs or fails | Run npm install -g @aerostack/gateway instead, then use "command": "aerostack-gateway" | | "Token invalid" in --check | Regenerate token at dashboard → Workspace → Tokens | | "0 tools found" | Add MCP servers to your workspace in the dashboard first | | OpenClaw: tools not showing | Send a message via Telegram or another channel to initialize the session | | Dashboard shows "No agents" | Run --check to verify, or wait 2 minutes for the heartbeat to register | | "Workspace unreachable" | Check the URL format: https://mcp.aerostack.dev/ws/your-workspace |

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

| Category | What it covers | |----------|---------------| | file_delete | Deleting or overwriting files | | shell_destructive | rm -rf, DROP TABLE, etc. | | git_push | git push, force push, git reset --hard | | config_modify | .env, credentials, production configs | | deploy | Deploy, publish, release to any environment | | database | Direct database mutations outside migrations |

Configuration

| Variable | Required | Description | |----------|----------|-------------| | AEROSTACK_WORKSPACE_URL | Yes | Your workspace URL (https://mcp.aerostack.dev/ws/...) | | AEROSTACK_TOKEN | Yes | Workspace token (mwt_...) — get from dashboard | | AEROSTACK_LOG_LEVEL | No | Log level: debug, info (default), warn, error |

CLI Flags

| Flag | Description | |------|-------------| | --check | Run connection diagnostics and exit (no MCP server started) |

Supported MCP Methods

| Method | Description | |--------|-------------| | tools/list | List all tools from all workspace servers | | tools/call | Call a namespaced tool (with approval handling) | | resources/list | List resources from all workspace servers | | resources/read | Read a specific resource | | prompts/list | List prompts from all workspace servers | | prompts/get | Get a prompt with arguments |

Requirements

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

Links

• Aerostack Docs
• Aerostack Admin
• MCP Specification

License

MIT