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>

Note

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.

Claude Desktop

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.

Claude Code

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..."

Cursor

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.

Windsurf

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..."
      }
    }
  }
}

Any MCP Client

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"]
        }
      }
    ]
  }
}

Note

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.

Note

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.