Connect via Gateway

Every workspace has a gateway URL that speaks the MCP protocol. Connect any MCP-compatible client — Claude Desktop, Cursor, your own applications — using this single endpoint and a bearer token.

Your Gateway URL

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

The gateway is also available at https://api.aerostack.dev/api/gateway/ws/<workspace-slug>. Both URLs are equivalent.

Authenticate every request with a workspace token in the Authorization header:

Authorization: Bearer mwt_7a3f9c1e8b4d2f6a...

See Tokens for how to create tokens.

Connect from LLM Clients

When you create a token in the dashboard, the response includes a ready-to-use mcp_json configuration block. Copy it directly into your client.

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-workspace": {
      "url": "https://mcp.aerostack.dev/ws/my-workspace",
      "headers": {
        "Authorization": "Bearer mwt_7a3f9c1e8b4d2f6a..."
      }
    }
  }
}

On macOS, this file is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, it is at %APPDATA%\Claude\claude_desktop_config.json.

Restart Claude Desktop after editing the config. Your workspace tools will appear in the tools panel.

Add the server to your Claude Code MCP configuration:

{
  "mcpServers": {
    "my-workspace": {
      "url": "https://mcp.aerostack.dev/ws/my-workspace",
      "headers": {
        "Authorization": "Bearer mwt_7a3f9c1e8b4d2f6a..."
      }
    }
  }
}

Or use the CLI:

claude mcp add my-workspace https://mcp.aerostack.dev/ws/my-workspace \
  --header "Authorization: Bearer mwt_7a3f9c1e8b4d2f6a..."

In Cursor, go to Settings > MCP Servers and add a new server:

Name: my-workspace
Type: HTTP (Streamable)
URL: https://mcp.aerostack.dev/ws/my-workspace
Headers: Authorization: Bearer mwt_7a3f9c1e8b4d2f6a...

Cursor will automatically discover your workspace tools and make them available in chat.

In Windsurf, add the server to your MCP configuration:

{
  "mcpServers": {
    "my-workspace": {
      "serverUrl": "https://mcp.aerostack.dev/ws/my-workspace",
      "headers": {
        "Authorization": "Bearer mwt_7a3f9c1e8b4d2f6a..."
      }
    }
  }
}

The gateway speaks standard JSON-RPC 2.0 over HTTP (Streamable HTTP transport). Any client that supports the MCP protocol can connect:

curl -X POST https://mcp.aerostack.dev/ws/my-workspace \
  -H "Authorization: Bearer mwt_7a3f9c1e8b4d2f6a..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Supported Methods

The gateway supports four JSON-RPC methods:

`initialize`

Handshake method. Returns gateway capabilities and protocol version.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-app", "version": "1.0.0" }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "aerostack-mcp-gateway", "version": "1.0.0" }
  }
}

`ping`

Health check. Returns an empty result.

`tools/list`

Returns all tools from all enabled servers in the workspace. The gateway fans out to each server in parallel and merges the results.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "github__create_issue",
        "description": "Create a new GitHub issue",
        "inputSchema": {
          "type": "object",
          "properties": {
            "title": { "type": "string" },
            "body": { "type": "string" },
            "repo": { "type": "string" }
          },
          "required": ["title", "repo"]
        }
      }
    ]
  }
}

The fan-out has a per-server timeout. If a server does not respond in time, its tools are omitted from the result — the request still succeeds with tools from the responsive servers.

`tools/call`

Call a specific tool. Use the namespaced tool name (for example, github__create_issue). The gateway parses the prefix, routes to the correct upstream server, and returns the result.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "github__create_issue",
    "arguments": {
      "title": "Fix login bug",
      "repo": "my-org/my-repo"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Created issue #42: Fix login bug"
      }
    ]
  }
}

Cross-LLM Adapter Endpoints

If you are building with a non-MCP LLM provider, the gateway provides adapter endpoints that translate MCP tools into provider-specific schemas.

OpenAI Function Calling Format

GET https://mcp.aerostack.dev/ws/:slug/openai-tools
Authorization: Bearer mwt_...

Returns tools formatted for OpenAI’s function calling API:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "github__create_issue",
        "description": "Create a new GitHub issue",
        "parameters": { "type": "object", "properties": { ... } }
      }
    }
  ]
}

Google Gemini Format

GET https://mcp.aerostack.dev/ws/:slug/gemini-tools
Authorization: Bearer mwt_...

Returns tools formatted for Gemini’s function declaration API.

These adapters let you use Aerostack workspace tools with any LLM. Fetch the tool schemas from the adapter endpoint, pass them to your LLM, and call tools/call on the gateway when the model requests a function call.

Rate Limiting and Timeouts

Parameter	Value
Requests per minute per token	120
Max request body size	1 MB
Tool call upstream timeout	15 seconds
Tool list fan-out timeout per server	10 seconds

When rate-limited, the gateway returns HTTP 429.

Error Responses

HTTP Status	JSON-RPC Code	Meaning
401	N/A	Invalid or missing token
404	N/A	Workspace not found
413	N/A	Request body exceeds 1 MB
429	-32000	Rate limit exceeded
200	-32600	Invalid JSON-RPC request
200	-32601	Method not found
200	-32000	Upstream server error or timeout

Caching and Propagation

The gateway caches workspace configuration for performance. Any write operation to the workspace (add server, revoke token, update secret) invalidates the cache immediately. Changes take effect within seconds.

Add Tools Tokens