SmartAlex Documentation - AI Voice Assistant Platform

SmartAlex is agent-native by design. It works exceptionally well with Claude Code and every other MCP client, and the voice widget drops into any generated frontend. This page covers the AI-native builder tools beyond Lovable: Cursor, VS Code, v0, Bolt, and Replit. There are two ways to bring SmartAlex into your workflow. Pick based on what the tool is for.

Mode A: connect the MCP server

In Cursor or VS Code, wire up the MCP server so your coding agent can create voice agents, run campaigns, and read call transcripts without leaving the editor.

Mode B: embed the widget

In a v0, Bolt, or Replit generated app, paste one script tag (or a small React snippet) to put a live voice and chat agent on the page.

Mode A: connect the MCP server in Cursor or VS Code

The MCP server exposes 28 tools across voice agents, contacts, campaigns, calls, deals, phone numbers, webhooks, and widgets. Once connected, your editor agent can drive all of them. For example, ask your Cursor agent to build a voice agent straight from a business website URL: SmartAlex scrapes the site, generates an optimized prompt, and deploys a live agent in about 30 to 60 seconds. That is Cursor voice AI with no glue code. Cursor and VS Code both use the local (stdio) transport via the @smartalex/mcp-server npm package.

Create an API key

Keys are generated in the Developer Portal at app.getsmartalex.com/developers under the API Keys tab. This requires the Power Tools add-on ($29/month) and a super-admin role on the workspace. Keys start with sa_live_ (production) or sa_test_ (sandbox), and are shown once at creation.

Add the config file for your editor

Cursor reads .cursor/mcp.json; VS Code (GitHub Copilot) reads .vscode/mcp.json. Paste your key in place of the placeholder.

{
  "mcpServers": {
    "smartalex": {
      "command": "npx",
      "args": ["-y", "@smartalex/mcp-server"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

{
  "servers": {
    "smartalex": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@smartalex/mcp-server"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

Reload the editor and start asking

Restart or reload the window so the client picks up the server. Then try: “List my SmartAlex agents”, or “Create a voice agent from https://example.com and assign a phone number.”

On Windows, wrap the launcher: set "command": "cmd" and "args": ["/c", "npx", "-y", "@smartalex/mcp-server"]. Windsurf and Gemini CLI follow the same stdio pattern (they read ~/.gemini/settings.json and their own config).

Prefer to test without a key first? The one-line hosted variant for Claude Code is claude mcp add smartalex -- npx @smartalex/mcp-server for local stdio, or the cloud endpoint over OAuth. See MCP getting started for every client.

v0, Bolt, and Replit generate frontends fast. To put a v0 voice agent (or Bolt voice AI, or a Replit AI phone agent) on the page, embed the SmartAlex widget. It is a single external script from the SmartAlex storage host, so there is no package to install. The widget reads its published config (variant, colours, agent) at load time, so you can restyle it in Widget Studio later without touching the generated code again. Find your data-tenant-id in the widget code panel in-app, or fetch it with the MCP tool smartalex_get_widget_install_code.

<!-- SmartAlex Widget: paste just before </body> -->
<script
  src="https://api.getsmartalex.com/storage/v1/object/public/widget-assets/smartalex-widget.js"
  data-tenant-id="YOUR_TENANT_ID"
  async>
</script>

import { useEffect } from 'react';

export default function Layout({ children }) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.getsmartalex.com/storage/v1/object/public/widget-assets/smartalex-widget.js';
    script.setAttribute('data-tenant-id', 'YOUR_TENANT_ID');
    script.async = true;
    document.body.appendChild(script);
    return () => { document.body.removeChild(script); };
  }, []);

  return <>{children}</>;
}

For a static HTML export, use the script tag exactly as you would on WordPress or Shopify. For React or Next.js output, inject the script from the root layout or app component. One widget is active per workspace at a time; pick the variant (voice-first pill, voice-only, chat bar, side panel, or the full Ask Alex messenger) in Widget Studio.

Which path for which tool

Tool	What it is	Recommended path
Cursor	AI code editor	Connect the MCP server (manage SmartAlex from chat)
VS Code (GitHub Copilot)	AI code editor	Connect the MCP server
v0	Generates React and Next.js UIs	Embed the widget (React snippet)
Bolt	Generates full-stack apps	Embed the widget (static or React)
Replit	AI app builder plus IDE	Embed the widget; connect the MCP server in the Replit shell if your agent supports stdio

The live programmatic surfaces today are the MCP server and Custom HTTP Tools. A public REST API and a TypeScript SDK are in private beta (coming soon). If a shipped REST API is a hard requirement right now, factor that into your timing. The website widget always embeds via the script tag or React component shown above.

The speech, language, and voice models behind Alex are curated and high-accuracy, kept abstracted, so there is nothing to tune and no pipeline to assemble. You describe the agent (or point it at a URL) and ship.

Build with Claude Code

The first-class, agent-native path: connect the hosted MCP server over OAuth in one command.

Add SmartAlex to Lovable

The Lovable-specific guide for embedding voice in a generated app.

MCP getting started

Every supported client, cloud and local, with copy-paste commands.

Install the widget

Platform-by-platform embed guides and every config option.

Add SmartAlex to Cursor, v0, Bolt, and Replit apps

Mode A: connect the MCP server

Mode B: embed the widget

Mode A: connect the MCP server in Cursor or VS Code

Mode B: embed the widget in generated apps

Which path for which tool

Build with Claude Code

Add SmartAlex to Lovable

MCP getting started

Install the widget

Mode A: connect the MCP server

Mode B: embed the widget

​Mode A: connect the MCP server in Cursor or VS Code

​Mode B: embed the widget in generated apps

​Which path for which tool

​Related

Build with Claude Code

Add SmartAlex to Lovable

MCP getting started

Install the widget

Mode A: connect the MCP server in Cursor or VS Code

Mode B: embed the widget in generated apps

Which path for which tool

Related