# Waspes Developer Portal, API & Model Context Protocol (MCP) Documentation

Canonical URL: https://waspes.com/developers  
API Reference URL: https://waspes.com/api  
OpenAPI 3.1 Specification: https://waspes.com/openapi.json  
MCP Server Endpoint: `https://waspes.com/api/mcp` (Versioned: `https://waspes.com/api/v1/mcp`)  
MCP Server Card: https://waspes.com/.well-known/mcp/server-card.json  

## 1. Overview & Sandbox Environment
Waspes provides a Streamable HTTP **Model Context Protocol (MCP)** server and JSON-RPC 2.0 API that allows Claude, Cursor, ChatGPT, Windsurf, and custom autonomous agents to generate complete full-stack HTML5/CSS/JS websites, standalone contact forms, architectural master prompts, and textured 3D / Roblox Studio models.

- **Anonymous Sandbox Mode:** Call `generate_website` or `start_website` + `get_website` without an API key to test website generation in the capped sandbox environment.
- **Authenticated Production Mode:** Generate a `wsp_live_...` API key in your Waspes account at `https://waspes.com/api` and pass it in `Authorization: Bearer wsp_live_...` or `X-API-Key: wsp_live_...`.

## 2. Quickstart: Connect Claude Desktop, Cursor, or Custom Agents

### MCP Client Configuration (`mcp.json` / `claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "waspes": {
      "url": "https://waspes.com/api/mcp",
      "headers": {
        "Authorization": "Bearer wsp_live_YOUR_API_KEY"
      }
    }
  }
}
```

### cURL Quickstart: List Tools & Start an Async Website Build
```bash
# 1. Discover available MCP tools
curl -sS https://waspes.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2026-10-24" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# 2. Start an asynchronous website generation job (~60s build)
curl -sS https://waspes.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wsp_live_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "start_website",
      "arguments": {
        "brief": "Modern SaaS landing page for an AI analytics platform with pricing table and contact form",
        "style": "glassmorphism",
        "deliver_email": "hello@waspes.com"
      }
    }
  }'
```

## 3. Available MCP Tools (8 Tools)
| Tool Name | Read-Only | Idempotent | Required Params | Description |
|---|---|---|---|---|
| `start_website` | `false` | `false` | `brief` | Start an async website build and return a `jobId` immediately. |
| `get_website` | `true` | `true` | `jobId` | Poll an async website build until finished HTML is returned. |
| `generate_website` | `false` | `false` | `brief` | Synchronous full-page website generator (~1–3 min). |
| `generate_form` | `false` | `false` | `brief` | Generate a standalone wired HTML contact form with email delivery. |
| `generate_master_prompt` | `true` | `false` | `idea` | Expand a short idea into a comprehensive master prompt. |
| `list_3d_models` | `true` | `true` | *(optional `limit`)* | List generated 3D models (`taskId`, `title`, `thumbnail`). |
| `connect_roblox` | `true` | `true` | *(optional `format`)* | Get setup instructions and plugin URL for Roblox Studio sync. |
| `send_to_roblox` | `false` | `false` | `taskId` | Stream a 3D model directly into an open Roblox Studio place as `MeshParts`. |

## 4. Versioning, Rate Limits & Error Model
- **Versioning Policy:** Use `/api/v1/mcp` or pass `X-API-Version: 2026-10-24`. Deprecated endpoints emit RFC `Deprecation` and `Sunset` headers at least 90 days prior to removal.
- **Rate Limiting:** Default limit is 60 requests/minute. Every response includes `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers (plus `Retry-After` on HTTP 429).
- **Structured JSON Error Model:** Errors return structured JSON with `code`, `message`, `resolution`, and JSON-RPC 2.0 `error` objects (`-32700` Parse error, `-32600` Invalid Request, `-32601` Method not found, `-32602` Invalid params).