MCP Setup

Looking for OAuth?

Claude Desktop and Claude Code support OAuth-based connections — no API key needed in your config file. See Connect via OAuth.

Hosted Server (Recommended)

Connect directly to the Waxell-hosted MCP server. No install required.

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "waxell": {
      "type": "sse",
      "url": "https://mcp-gateway.waxell.dev/mcp",
      "headers": {
        "Authorization": "Bearer wax_sk_your_key_here"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "waxell": {
      "type": "sse",
      "url": "https://mcp-gateway.waxell.dev/mcp",
      "headers": {
        "Authorization": "Bearer wax_sk_your_key_here"
      }
    }
  }
}

Cursor

Add to Cursor's MCP settings (Settings > MCP Servers):

{
  "waxell": {
    "type": "sse",
    "url": "https://mcp-gateway.waxell.dev/mcp",
    "headers": {
      "Authorization": "Bearer wax_sk_your_key_here"
    }
  }
}

VS Code

Add to your MCP settings:

{
  "mcpServers": {
    "waxell": {
      "type": "sse",
      "url": "https://mcp-gateway.waxell.dev/mcp",
      "headers": {
        "Authorization": "Bearer wax_sk_your_key_here"
      }
    }
  }
}

Run Locally (Alternative)

If you prefer to run the MCP server on your machine (for offline docs access or self-hosted setups):

# Using uvx (recommended — no install needed)
uvx waxell-developer-mcp

# Or install with pip
pip install waxell-developer-mcp
waxell-dev-mcp

Then configure your MCP client for stdio transport:

{
  "mcpServers": {
    "waxell": {
      "type": "stdio",
      "command": "uvx",
      "args": ["waxell-developer-mcp"],
      "env": {
        "WAXELL_DEV_API_KEY": "wax_sk_your_key_here"
      }
    }
  }
}

Getting an API Key

Option 1: Sign up through your agent (recommended)

After connecting to the MCP server, ask your coding agent:

"Sign me up for Waxell"

It calls waxell_signup, which opens a browser link. Complete the form in your browser — no password ever touches your editor. Then waxell_signup_status retrieves your API key and saves it to ~/.waxell/config.

Option 2: From the web dashboard

1. Go to app.waxell.dev/settings/api-keys
2. Create a new API key
3. Copy the wax_sk_... key into your MCP config

Option 3: Config file

The server reads ~/.waxell/config as a fallback when no API key is provided via headers or environment variables:

{
  "api_key": "wax_sk_your_key_here",
  "api_url": "https://app.waxell.dev"
}

Configuration

Environment Variables

Variable	Default	Description
WAXELL_DEV_API_KEY	(none)	API key for stdio mode. Falls back to ~/.waxell/config.
WAXELL_DEV_API_URL	https://app.waxell.dev	Waxell API URL. Change for self-hosted deployments.
WAXELL_DEV_TRANSPORT	stdio	Transport mode: stdio (local) or sse (deployed).
WAXELL_DEV_HOST	0.0.0.0	Bind address for SSE mode.
WAXELL_DEV_PORT	8004	Listen port for SSE mode.

In SSE mode (hosted), each client authenticates via the Authorization: Bearer <key> header instead of the server-side environment variable.

Config Resolution Order

1. HTTP headers (SSE mode) — Authorization: Bearer <key> or X-Wax-Key header
2. Environment variables — WAXELL_DEV_API_KEY, WAXELL_DEV_API_URL
3. Config file — ~/.waxell/config (JSON)
4. Defaults

Verify

After setup, ask your coding agent:

"Check my Waxell connection"

It calls waxell_check_connection and returns your tenant info, agent count, and guided next steps. If you see an error, check your API key.

Docs-Only Mode

The documentation resources work without an API key. If you just want the agent to learn the SDK without querying live data, connect without the headers field or omit WAXELL_DEV_API_KEY. The docs resources will still be available, and tools will return a helpful setup message.