mcp

Install the Roxels MCP

The Roxels MCP is a small command-line server that runs on your machine and exposes the Roxels API as tools your AI assistant can call. Once installed and connected, Claude Code, Cursor, or any MCP-compatible client can manage your templates, configure webhooks, generate embed code, and ask questions about your sessions — all on your behalf.

If you're signed in, the easiest path is the interactive install page at app.roxels.ai/dashboard/connect/mcp — it walks you through the same steps below with a live status indicator that flips green the moment your install succeeds.

You'll need

A Roxels API key — generate one at app.roxels.ai → Settings → API Keys.
uv — a small Python package manager. You don't need Python installed first; uv brings its own.
An MCP-compatible client: Claude Code, Cursor, Claude Desktop, or similar.

1. Check if you already have uv

Open any terminal and run:

uvx --version

If you see a version number (e.g. uv 0.5.4), skip to step 3. If you see command not found, do step 2 first.

2. Install uv (only if step 1 said "command not found")

uv is the runtime that runs the Roxels MCP. It's a small Rust binary (~30 MB) — installing it does not require Python.

macOS or Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

macOS with Homebrew (optional):
```
brew install uv
```

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After installing, open a brand-new terminal — the installer edits your shell rc and the old terminal won't pick that up. Then run uvx --version again. You should see a version number.

If you still get command not found, your PATH is missing ~/.local/bin. On macOS/Linux, run:

export PATH="$HOME/.local/bin:$PATH"

and add that line to your shell rc file (~/.bashrc, ~/.zshrc, etc.) so it sticks.

3. Register the MCP with your AI assistant

Pick your client.

Claude Code

Run this in a terminal — not inside an active Claude Code session:

claude mcp add roxels -e ROXELS_API_KEY=sk-your-key-here -- uvx roxels-mcp

Replace sk-your-key-here with your actual API key. Then open a Claude Code session and run /mcp. You should see roxels — connected.

Cursor

Create or edit .cursor/mcp.json at your project root:

{
  "mcpServers": {
    "roxels": {
      "type": "stdio",
      "command": "uvx",
      "args": ["roxels-mcp"],
      "env": { "ROXELS_API_KEY": "sk-your-key-here" }
    }
  }
}

Restart Cursor. The Roxels MCP will appear under Settings → MCP.

Claude Desktop

Edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the same JSON block as the Cursor example and restart Claude Desktop.

4. Verify

In your client, ask: "List my Roxels templates." The assistant should call list_templates and return your templates.

You can also open the install status page in the dashboard — when your MCP runs successfully, the status pill flips to Connected within a few seconds.

Troubleshooting

"uvx: command not found" after installing uv

You probably haven't opened a new terminal yet. Close it and open a fresh one. If that still doesn't help on macOS/Linux, run export PATH="$HOME/.local/bin:$PATH" and add it to your shell rc.

The dashboard status pill stays gray after I run the install command

Smoke-test the MCP directly in a terminal with the same API key:

ROXELS_API_KEY=sk-your-key-here uvx roxels-mcp

The first run takes 15–60 seconds (uv is downloading Python and the package). After that, the process pauses silently waiting on stdin — that's success. Press Ctrl-C to stop, then refresh the dashboard page. If you see an error message instead, that's your real failure mode.

"ROXELS_API_KEY was rejected (401)"

Your API key is wrong, expired, or revoked. Generate a new one at Settings → API Keys and update your MCP config.

Claude Code says "Failed to connect" with no detail

Run claude mcp list and copy the registered command. Then run that command directly in a terminal — the error message there is the real one. Claude Code's "Failed to connect" is generic; it does not surface the underlying spawn error.

Behind a corporate firewall

If uvx can't reach pypi.org, point it at your internal mirror via the UV_INDEX_URL environment variable. If you're stuck, reach out — we can pair on this.

Upgrading

uvx always runs the latest version of roxels-mcp from PyPI by default — your install upgrades itself the next time you start a session. If you used uv tool install roxels-mcp for a persistent install, upgrade with:

uv tool upgrade roxels-mcp

We bump the version when new capabilities ship. Stale installs miss the latest tools and recommendations.

Security

The API key is sensitive. Treat it like any other secret. Don't commit it; use env vars or a secrets manager.
The MCP server is local. Nothing leaves your machine except API calls to api.roxels.ai (over TLS).
Permissions match your API key. The assistant can do anything your key can do — including create and modify templates.