roxels-mcp

Roxels MCP Server

Under construction. Roxels is in early access. The platform, docs site, and some features are actively being built. Everything in this MCP server works against the live API, but expect rough edges and breaking changes as we iterate. If you run into issues, reach out to us directly.

mcp-name: ai.roxels/roxels-mcp

What is Roxels?

Roxels is an AI-powered interview platform. You define what you want to learn (a template with goals and extraction schemas), and Roxels conducts a voice conversation with your user to collect that information — structured data, not just transcripts.

Think of it as a programmable phone call: you configure the interview, embed it in your app or share a link, and get structured JSON back via webhooks or API.

What does this MCP server do?

This MCP server lets AI agents (Claude Code, Claude Desktop, Cursor, or any MCP-compatible client) manage and integrate Roxels programmatically. Instead of clicking through a dashboard, your AI assistant can:

• Create interview templates by opening a voice conversation with the Roxels setup assistant — describe what you want, and a fully configured template is created automatically
• Configure data extraction — define output schemas, set up webhooks, choose what structured data to collect
• Generate embed code — ready-to-paste HTML/JS snippets in three presentation modes:
  • Modal — built-in centered dialog widget
  • Compact — built-in floating bottom-right panel widget
  • Headless — no Roxels UI at all; you render your own buttons and subscribe to events (voice_state, understanding, complete, …) while Roxels handles mic, audio, screenshare, and the realtime connection in an invisible iframe
• Monitor interviews — list interviews, read transcripts, view extracted findings
• Manage everything via API — CRUD on templates, persons, embed keys, and output configurations

For developers

If you're integrating Roxels into your product, this MCP server turns a multi-step manual setup into a single AI-assisted session:

• Install the MCP → your AI assistant gets access to 16 Roxels tools
• Tell your AI "set up a customer feedback interview with a webhook to our API"
• The AI creates the template, configures the webhook + schema, generates embed code, and hands you a working integration

No dashboard, no docs to read, no copy-pasting config.

For AI agents

This server exposes the Roxels platform as structured tools with typed parameters and detailed descriptions. Key capabilities:

Tool	What it does
create_template_interactive	Opens a browser to a voice conversation that creates a template — the fastest way to configure an interview
configure_output	Adds webhook, structured extraction, email, or Excel outputs to a template
get_embed_code	Returns a ready-to-paste HTML/JS snippet. Pick display="modal", "compact", or "headless" (bring-your-own-UI).
get_template_schema	Returns the full schema reference so you know what values are valid
create_embed_key	Generates a publishable client-side key for the embed widget
list_templates / get_template	Browse and inspect existing templates
list_interviews / get_interview	View interview results, transcripts, and extracted data

All 16 tools have detailed docstrings. Call get_template_schema first to understand the data model.

Setup

1. Get an API key

Sign up at app.roxels.ai, go to Settings → API Keys, and create a key.

2. Install

pip install roxels-mcp

Or run directly with uvx:

uvx roxels-mcp

3. Configure your MCP client

Claude Code (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "roxels": {
      "command": "roxels-mcp",
      "env": {
        "ROXELS_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

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

4. Verify

Ask your AI assistant: "Use the whoami tool to check my Roxels connection."

Environment variables

Variable	Required	Default	Description
ROXELS_API_KEY	Yes	—	Your Roxels API key (sk-...)
ROXELS_API_URL	No	https://api.roxels.ai	API base URL (override for self-hosted or development)

Example: Full integration in one session

You: "Set up a customer onboarding interview that collects company name,
      employee count, and main pain points. Send results to our webhook
      at https://api.myapp.com/webhooks/roxels with our auth header.
      Then give me the embed code."

AI assistant:
  1. Calls create_template_interactive → opens browser, you talk to the AI
  2. Calls configure_output → adds webhook with schema + headers
  3. Calls create_embed_key → generates a publishable key
  4. Calls get_embed_code → returns the HTML/JS snippet
  5. Done — paste the snippet, interviews are live

Security

• API keys (sk-...) authenticate all requests. Keep them server-side.
• Embed keys (rk-...) are safe for client-side code — scoped to one template, can only create sessions.
• The MCP server validates all URLs before opening your browser (only app.roxels.ai origins are trusted).
• All traffic is HTTPS. No data is stored locally.

Tools reference

Group	Tool	Description
Templates	list_templates	List all active templates
	get_template	Get template details (goals, settings, outputs)
	create_template	Create a template programmatically
	update_template	Update template fields
	create_template_interactive	Create a template via voice conversation (opens browser)
	modify_template_interactive	Modify a template via voice conversation (opens browser)
Interviews	list_interviews	List interviews with filters
	get_interview	Get full results (summary, findings, transcript)
	list_persons	List persons (interviewees)
	create_person	Create a person record
Integration	configure_output	Add/replace outputs (webhook, structured, email, excel, report)
	get_embed_config	Get the embed widget SDK reference
	create_embed_key	Generate a publishable embed key
	get_embed_code	Generate a ready-to-paste embed snippet (modal / compact widget, or headless bring-your-own-UI)
Utilities	get_template_schema	Get the full schema reference for templates and outputs
	whoami	Verify API key and connection

License

MIT