SmartAlex Documentation - AI Voice Assistant Platform

Windsurf’s Cascade agent can talk to SmartAlex directly over the Model Context Protocol. Once you add the SmartAlex MCP server, your coding agent gains 28 tools to build voice agents, wire the widget into whatever app you are shipping, run outbound campaigns, and move deals through the pipeline. This is real Windsurf voice AI: you stay in the editor, describe the outcome, and Cascade drives the account.

SmartAlex is built for AI-native builders. The MCP server is a first-class surface, so the same connection works across Windsurf, Cursor, Claude Code, and any MCP client. No native “Windsurf plugin” to install: it is a standard stdio MCP server.

How the connection works

Windsurf launches the SmartAlex MCP server locally over stdio and authenticates with your workspace API key. The key scopes every call to your tenant, and the gateway enforces isolation and rate limits.

Before you connect

Add Power Tools

MCP API keys are gated behind the Power Tools add-on ($29/month on Professional, included on Enterprise). See add-ons or pricing.

Generate an API key

Open the Developer Portal in the SmartAlex dashboard side nav. You need a super-admin role on the workspace. Production keys start with sa_live_, test keys with sa_test_. The key is shown once at creation (only a hash is stored), so copy it immediately. A lost key is regenerated, not recovered.

Add the SmartAlex MCP server to Windsurf

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json using an mcpServers block. Add SmartAlex to it, then reload the server list from the Cascade MCP panel.

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

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

Prefer to test the server first? Run it standalone in a terminal before wiring it into Windsurf:

export SMARTALEX_API_KEY=sa_live_your_key_here
npx @smartalex/mcp-server

After saving, open the Cascade MCP panel, refresh, and confirm smartalex appears with its tools loaded. That confirms your SmartAlex Windsurf MCP link is live.

Three prompts to try in Cascade

Paste these into Cascade once the server is connected. They map to real tool flows, so the agent will ask for the details it needs and then execute.

Create a voice agent for my dental practice using our website URL to
auto-build the persona. Make it a warm front-desk receptionist that books
appointments. When it is deployed, give me the widget install snippet so I
can paste it into the Next.js project open in this workspace.

List my voice agents and their phone numbers. Then start an outbound
campaign that calls every contact created in the last 7 days with a short
follow-up script, and show me the campaign status once it is scheduled.

Pull the transcript summary from my most recent completed call, create a
deal for that contact in the pipeline, and move it to the Qualified stage
with a note about what they asked for.

When Cascade returns the widget snippet, it is the same one-line script tag SmartAlex generates for any site:

<script src="https://api.getsmartalex.com/storage/v1/object/public/widget-assets/smartalex-widget.js" data-tenant-id="YOUR_TENANT_ID" async></script>

For a React or Next.js project, inject it from your root layout instead. See widget install for the component pattern.

What the agent can do

The server exposes 28 tools (all prefixed smartalex_), 7 read-only resources, and 5 prompt templates across 8 domains. 14 tools read, 14 write.

Domain	Tools	What Cascade can do
Agents	5	Create from a URL or brief, update persona and settings, deploy, delete
Contacts	4	Create, look up, update, and organise your CRM records
Phone numbers	3	List, provision, and manage numbers attached to agents
Campaigns	5	Create, schedule, start, monitor, and manage outbound campaigns
Calls	2	Read call records and transcript summaries
Deals	4	Create, update, move stages, and delete pipeline deals
Webhooks	3	Subscribe, list active subscriptions, and remove them
Platform & widgets	2	Fetch the widget install code and workspace info

Three tools are destructive: smartalex_delete_agent, smartalex_delete_deal, and smartalex_delete_webhook. Cascade will run them if you ask, so confirm before you approve a delete. Rate limits are 100 requests per minute per workspace.

The voice stack is curated, high-accuracy speech, language, and voice models, kept abstracted behind the platform. Agent records report voice_provider: "cloud". You operate voice agents through SmartAlex without assembling or tuning any underlying components yourself.

Webhooks and custom HTTP tools

Cascade can create webhook subscriptions through MCP, and each subscription returns an HMAC-SHA256 signing secret once at creation for verifying delivery. Named events include call.completed, deal.stage_changed, contact.created, and campaign.completed.

Subscription management is live today. Outbound event delivery is in private beta, so do not rely on real-time event push for production yet. For live in-call integrations, use Custom HTTP Tools (part of Power Tools), which let an agent call your own HTTPS endpoint mid-call. A public REST API and TypeScript SDK are coming soon in private beta.

MCP getting started

Full setup across every MCP client, keys, and transports.

Tools reference

Every one of the 28 tools with inputs and outputs.

Build with Cursor, v0 and Bolt

The same MCP flow in other agentic editors.

Build with Claude Code

Connect the hosted server over OAuth from the CLI.

​How the connection works

​Before you connect

​Add the SmartAlex MCP server to Windsurf

​Three prompts to try in Cascade

​What the agent can do

​Webhooks and custom HTTP tools

​Related

MCP getting started

Tools reference

Build with Cursor, v0 and Bolt

Build with Claude Code

How the connection works

Before you connect

Add the SmartAlex MCP server to Windsurf

Three prompts to try in Cascade

What the agent can do

Webhooks and custom HTTP tools

Related