# Connect via Gateway > How to connect Claude Desktop, Cursor, and any MCP client to your workspace using the gateway URL. 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/ ``` The gateway is also available at `https://api.aerostack.dev/api/gateway/ws/`. Both URLs are equivalent. Authenticate every request with a workspace token in the `Authorization` header: ``` Authorization: Bearer mwt_7a3f9c1e8b4d2f6a... ``` See [Tokens](/workspaces/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`: ```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: ```json { "mcpServers": { "my-workspace": { "url": "https://mcp.aerostack.dev/ws/my-workspace", "headers": { "Authorization": "Bearer mwt_7a3f9c1e8b4d2f6a..." } } } } ``` Or use the CLI: ```bash 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: ```json { "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: ```bash 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. ```json { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "my-app", "version": "1.0.0" } } } ``` **Response:** ```json { "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. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } ``` **Response:** ```json { "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. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "github__create_issue", "arguments": { "title": "Fix login bug", "repo": "my-org/my-repo" } } } ``` **Response:** ```json { "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: ```json { "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.