> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getsmartalex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use SmartAlex with Windsurf

> Connect the SmartAlex MCP server to Windsurf so Cascade can build and operate AI voice agents straight from your editor.

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.

<Note>
  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.
</Note>

## 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.

```mermaid theme={null}
flowchart LR
  A[Windsurf Cascade] -->|stdio| B["@smartalex/mcp-server"]
  B -->|SMARTALEX_API_KEY| C[SmartAlex MCP gateway]
  C --> D[Agents, contacts, campaigns, deals, widget]
```

## Before you connect

<Steps>
  <Step title="Add Power Tools">
    MCP API keys are gated behind the **Power Tools** add-on (\$29/month on Professional, included on Enterprise). See [add-ons](/essentials/add-ons) or [pricing](/pricing).
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<CodeGroup>
  ```json macOS / Linux theme={null}
  {
    "mcpServers": {
      "smartalex": {
        "command": "npx",
        "args": ["-y", "@smartalex/mcp-server"],
        "env": {
          "SMARTALEX_API_KEY": "sa_live_your_key_here"
        }
      }
    }
  }
  ```

  ```json Windows theme={null}
  {
    "mcpServers": {
      "smartalex": {
        "command": "cmd",
        "args": ["/c", "npx", "-y", "@smartalex/mcp-server"],
        "env": {
          "SMARTALEX_API_KEY": "sa_live_your_key_here"
        }
      }
    }
  }
  ```
</CodeGroup>

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

  ```bash theme={null}
  export SMARTALEX_API_KEY=sa_live_your_key_here
  npx @smartalex/mcp-server
  ```
</Tip>

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.

<CodeGroup>
  ```text Build an agent, then embed it theme={null}
  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.
  ```

  ```text Run an outbound follow-up theme={null}
  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.
  ```

  ```text Update the pipeline from a call theme={null}
  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.
  ```
</CodeGroup>

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

```html theme={null}
<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](/essentials/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                        |

<Warning>
  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.
</Warning>

<Info>
  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.
</Info>

## 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`.

<Note>
  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.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="MCP getting started" icon="rocket" href="/mcp/getting-started">
    Full setup across every MCP client, keys, and transports.
  </Card>

  <Card title="Tools reference" icon="wrench" href="/mcp/tools-reference">
    Every one of the 28 tools with inputs and outputs.
  </Card>

  <Card title="Build with Cursor, v0 and Bolt" icon="code" href="/build-with/cursor-v0-bolt">
    The same MCP flow in other agentic editors.
  </Card>

  <Card title="Build with Claude Code" icon="terminal" href="/build-with/claude-code">
    Connect the hosted server over OAuth from the CLI.
  </Card>
</CardGroup>