Connect via OAuth

OAuth lets you connect Claude Desktop or Claude Code to Waxell by signing in through your browser — no API keys to copy into config files. Each connection automatically gets its own scoped API key, managed entirely behind the scenes. This is the recommended approach for Claude Desktop and Claude Code.

For API key authentication (Cursor, VS Code, or headless setups), see Setup with API Keys.

Prerequisites

• A Waxell account — sign up at app.waxell.dev if you do not have one
• Claude Desktop or Claude Code installed

Claude Desktop

Step 1: Open the config file

Locate your Claude Desktop config file:

OS	Config file path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Create the file if it does not exist.

Step 2: Add the Waxell MCP server

Add the following to your config file:

{
  "mcpServers": {
    "waxell": {
      "url": "https://dev-mcp.waxell.dev/mcp"
    }
  }
}

That is the entire config. No headers, no type, no API key — just the URL. OAuth handles authentication automatically.

note

If you already have other MCP servers configured, add the "waxell" entry inside the existing "mcpServers" object.

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop to pick up the new config.

Step 4: Sign in

On first connection, Claude Desktop opens your browser to the Waxell login page. Sign in with your email and password. If MFA is enabled on your account, complete the second factor.

Once you approve, the browser closes and Claude Desktop is connected.

tip

You only need to sign in on first connect and again after 30 days of inactivity. Between sessions, Claude Desktop refreshes your tokens automatically.

Claude Code

Step 1: Create or open .mcp.json

In your project root (or home directory for global config), create .mcp.json:

{
  "mcpServers": {
    "waxell": {
      "type": "url",
      "url": "https://dev-mcp.waxell.dev/mcp"
    }
  }
}

The "type": "url" tells Claude Code to use the Streamable HTTP transport with OAuth.

Step 2: Start Claude Code

Launch Claude Code in a terminal. It detects the MCP config and initiates the OAuth flow.

Step 3: Sign in

Claude Code opens your browser to the Waxell login page. Sign in and complete MFA if enabled. After approval, the terminal session is connected.

tip

Claude Code stores tokens locally. You will not need to sign in again until the refresh token expires (30 days of inactivity).

Verify Your Connection

Option 1: Ask your agent

After connecting, ask Claude:

"Check my Waxell connection"

It calls waxell_check_connection and returns your tenant info, agent count, and guided next steps.

Option 2: Check the Waxell dashboard

Go to app.waxell.dev/settings/connections and look for a new MCP connection entry with a recent "last used" timestamp.

For more details on viewing and revoking connections, see Managing Connections.

What Happens Behind the Scenes

When you connect, the MCP client and Waxell exchange a series of messages to establish a secure session:

1. Connect — The client sends an initial request, receives 401 Unauthorized
2. Discovery — The client fetches OAuth metadata from /.well-known/oauth-authorization-server
3. Client registration — The client registers itself and receives a client_id
4. Browser login — You sign in; the server issues an authorization code
5. Token exchange — The client exchanges the code (with PKCE proof) for access and refresh tokens
6. Authenticated access — Every subsequent MCP request includes the access token

Token	Lifetime	What it does
Access token	1 hour	Authenticates each MCP request
Refresh token	30 days	Gets new access tokens without re-login
Client registration	30 days	Cached client credentials

The access token embeds a scoped API key (wax_sk_...) so you never need to manage keys manually.

For the full protocol specification — PKCE details, request/response formats, error codes — see OAuth Flow.

Local Development

If you are running the MCP server locally (e.g., during development at http://localhost:8005), OAuth will not work directly because MCP clients expect HTTPS for OAuth discovery.

Use the mcp-remote bridge to proxy a local HTTP server through an OAuth-capable wrapper.

Claude Desktop with mcp-remote

{
  "mcpServers": {
    "waxell-local": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8005/mcp",
        "--allow-http"
      ]
    }
  }
}

Claude Code with mcp-remote

{
  "mcpServers": {
    "waxell-local": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8005/mcp",
        "--allow-http"
      ]
    }
  }
}

note

mcp-remote bridges stdio to HTTP so the MCP client communicates with your local server without requiring HTTPS or OAuth. For local development with API key auth (no bridge needed), see Setup with API Keys.

Troubleshooting

Browser does not open

• Claude Desktop: Ensure you are running the latest version. Older versions may not support OAuth-based MCP connections. Check that your config file has only "url" (no "type": "sse" or "headers").
• Claude Code: Check terminal output for error messages. Ensure .mcp.json has "type": "url".

"No tenant found" error after signing in

Your account is not associated with a workspace. Ask your team admin to invite you, or create a new workspace at app.waxell.dev.

Connection drops after an hour

This is normal. The access token expires hourly and the MCP client refreshes it automatically using the refresh token. If the refresh fails, you will be prompted to sign in again — this usually means the refresh token has also expired (30 days of inactivity).

"Invalid client" error

The client registration has expired (30-day TTL). Remove the cached client credentials and reconnect:

• Claude Desktop: Restart the app. It re-registers automatically.
• Claude Code: Delete the cached OAuth state and restart. Claude Code stores OAuth state in its local data directory.