> ## 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 Claude Code

> Build and operate a full voice AI platform from Claude Code. The SmartAlex MCP voice agent server lets you create an agent from a URL, run campaigns, and review calls, all from the terminal.

SmartAlex is built for AI-native builders, and it is first-class with Claude Code. Point Claude Code at the live SmartAlex MCP server and you can build **and** operate a complete voice platform without leaving your agent: spin up a voice agent for a clinic from a single URL, launch an outbound campaign, read call transcripts, and update a deals pipeline, all in one conversation.

Most voice tools give an AI agent docs to read. SmartAlex gives it a set of tools to act with. That is why building a voice agent from the terminal actually works here: every capability is exposed as an MCP tool with a clear scope, so Claude Code can plan a step, call the right tool, and show you the result.

<Note>
  Honest framing: SmartAlex is agent-native by design and works exceptionally well with Claude Code (our MCP server is live and listed in the Claude MCP directory). It works equally well with other MCP clients like Cursor, VS Code, Windsurf, ChatGPT, and Gemini CLI. This is not an exclusive or official partnership with Anthropic. Claude Code is simply the smoothest way in.
</Note>

## Why it fits Claude Code so well

Claude Code is at its best when it can act safely and reversibly. SmartAlex is designed for exactly that:

* **Everything is a tool with an explicit scope.** The server exposes 28 tools split into 14 read, 14 write, and 3 destructive operations. Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`), so Claude Code knows a call is a safe read, a retryable update, or a permanent delete before it runs it, and can confirm with you first.
* **Read and write are separable.** Hand a reporting session a `read` key and it physically cannot create, start, or delete anything: a write attempt returns a `403`. Give a build session a `write` key when you want it to ship.
* **Strict per-workspace isolation.** Every credential resolves to exactly one workspace, enforced at the gateway. An agent connected to your workspace can only ever see and touch your workspace, never another tenant's data.

The result: you can let Claude Code drive real operations on a live voice platform and still keep tight, predictable boundaries.

## Connect Claude Code to SmartAlex

The fastest path is the hosted cloud endpoint over OAuth: no install, no key to copy, no config file.

<CodeGroup>
  ```bash Cloud (OAuth, recommended) theme={null}
  claude mcp add --transport http smartalex https://api.getsmartalex.com/functions/v1/mcp-server
  ```

  ```bash Local (stdio, API key) theme={null}
  export SMARTALEX_API_KEY=sa_live_your_key_here
  claude mcp add smartalex -- npx @smartalex/mcp-server
  ```
</CodeGroup>

<Steps>
  <Step title="Add the server">
    Run the cloud command above. Claude Code registers the SmartAlex MCP server and prompts you to authenticate.
  </Step>

  <Step title="Approve in your browser">
    OAuth opens in the browser. Approve access, and the token binds to your active workspace. Nothing to paste back.
  </Step>

  <Step title="Ask it to do something">
    Type a plain request, for example "show me my SmartAlex contacts". Claude Code selects the right tool and runs it against your workspace.
  </Step>
</Steps>

<Info>
  **Prefer a local API key?** Generate one in the Developer Portal at `app.getsmartalex.com/developers` (API Keys tab), then use the local command above. Keys come in two environments, `sa_live_` (production) and `sa_test_` (sandbox), and carry a `read` or `write` scope. The Developer Portal requires the Power Tools add-on (\$29/month) and a super-admin role on the workspace. If you cannot see it, check both. A key is shown once at creation, so store it safely.
</Info>

## What your agent can operate

Once connected, Claude Code can run the whole platform through conversation. The 28 tools (all prefixed `smartalex_`) span eight domains:

| Domain               | What Claude Code can do                                                                      | Access         |
| -------------------- | -------------------------------------------------------------------------------------------- | -------------- |
| Voice agents         | Build an agent from a website URL or a full spec, update, activate, delete                   | Read and write |
| Contacts             | List, look up, create, update, tag and segment the CRM                                       | Read and write |
| Campaigns            | Create outbound campaigns, add contacts in batches, start calling, track progress            | Read and write |
| Calls                | Browse call history (direction, status, duration, sentiment, cost) and read full transcripts | Read only      |
| Deals                | List by stage, create with a value and linked contact, move `lead` to `closed_won`, delete   | Read and write |
| Phone numbers        | List active numbers, search available numbers by country, buy in E.164                       | Read and write |
| Webhooks             | Subscribe an HTTPS endpoint to events, list with failure counts, remove                      | Read and write |
| Platform and widgets | Check health and usage stats, fetch ready-to-paste widget install code                       | Read only      |

The headline capability: `smartalex_create_agent` takes a website URL, reads the business, generates an optimized prompt, and deploys a live voice agent in about 30 to 60 seconds. Underneath, SmartAlex runs a curated, high-accuracy speech, language, and voice stack, kept abstracted, so there is nothing for you to tune.

## Example prompts

Real requests you can paste into Claude Code once it is connected:

| Say this                                                                                                                             | What SmartAlex does                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| "Create a voice agent for this dental clinic from `brightsmiledental.com`, give it a warm first message, and assign a phone number." | Scrapes the site, builds and deploys a live agent, buys and attaches a number |
| "Add these 40 leads to a new outbound campaign, set calling hours to 9am to 5pm in `America/New_York`, then start it."               | Creates the campaign, batches in the contacts, and begins calling             |
| "Show me last week's calls with negative sentiment and pull the transcript for the longest one."                                     | Lists filtered call history, then reads the full transcript                   |
| "Move the Acme deal to `closed_won` and give me the widget install snippet for our Next.js site."                                    | Advances the pipeline stage and returns ready-to-paste embed code             |

<Tip>
  Because deletes are flagged `destructiveHint`, a request like "delete the old test agent" makes Claude Code confirm before it acts. Give a session a read-only key when you only want it to report.
</Tip>

## A full build, in one conversation

The point of building a voice agent from the terminal is that you never context-switch. A single Claude Code thread can carry a business from URL to live, calling agent:

```mermaid theme={null}
flowchart LR
  A[You describe the goal] --> B[Claude Code]
  B -->|smartalex_ tool call| C[SmartAlex MCP server]
  C -->|scoped to your workspace| D[Live voice platform]
  D -->|result and transcripts| B
  B -->|next step or confirm| A
```

You stay in the loop for anything that writes or deletes, Claude Code does the mechanical work, and every action is scoped to your workspace.

## Embed the result on your site

When the agent is ready, ask Claude Code for the widget code (`smartalex_get_widget_install_code`) and drop it in. For a static site, paste this single tag just before the closing `body` tag:

```html theme={null}
<!-- SmartAlex Widget -->
<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 app, inject it from your root layout:

```tsx theme={null}
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}</>;
}
```

The widget reads its published config (variant, colors, agent) at load time, so you can restyle it in Widget Studio later without touching the site again. This is the same pattern you use for a Lovable, v0, or Bolt export: static HTML gets the script tag, React output gets the `useEffect` injection.

## Live today, coming soon

<CardGroup cols={2}>
  <Card title="Live now" icon="circle-check">
    The MCP server (cloud and local) and Custom HTTP Tools are in production. These are the programmatic surfaces you build against today.
  </Card>

  <Card title="Coming soon" icon="clock">
    A public REST API and TypeScript SDK are in private beta. If a shipped REST API is a hard requirement right now, factor that into your timing.
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="MCP getting started" icon="rocket" href="/mcp/getting-started">
    Connect Claude Code, Cursor, VS Code, ChatGPT, or Gemini CLI in under two minutes.
  </Card>

  <Card title="What an AI agent can do" icon="robot" href="/mcp/agent-capabilities">
    The full 28-tool operating surface, scopes, and isolation model.
  </Card>

  <Card title="Build with Cursor, v0, and Bolt" icon="code" href="/build-with/cursor-v0-bolt">
    The same MCP server, from other AI-native builder tools.
  </Card>

  <Card title="Pricing and add-ons" icon="tag" href="/pricing">
    Plans, included minutes, and the Power Tools add-on that unlocks API keys.
  </Card>
</CardGroup>