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

# MCP Tools Reference

> Complete reference for all 28 SmartAlex MCP tools. Manage contacts, agents, campaigns, calls, deals, and webhooks from any MCP-compatible AI assistant.

# MCP Tools Reference

Complete reference for all 28 SmartAlex MCP tools, organized by domain. Each tool includes its parameters, response shape, and example usage.

All tool names are prefixed with `smartalex_` to avoid conflicts when used alongside other MCP servers.

***

## Contacts

### smartalex\_list\_contacts

List all contacts in the current workspace with pagination.

**Parameters:**

| Parameter  | Type    | Required | Description                              |
| ---------- | ------- | -------- | ---------------------------------------- |
| `page`     | integer | No       | Page number (default: 1)                 |
| `per_page` | integer | No       | Results per page (default: 25, max: 100) |

**Example usage:**

```
"Show me all my contacts"
"Show page 2 of contacts"
```

**Example response:**

```json theme={null}
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "first_name": "Sarah",
      "last_name": "Johnson",
      "email": "sarah@example.com",
      "phone": "+15551234567",
      "company": "Acme Corp",
      "tags": ["enterprise"],
      "status": "active",
      "created_at": "2026-03-01T10:30:00+00:00"
    }
  ],
  "meta": {
    "total": 21,
    "page": 1,
    "per_page": 25
  }
}
```

***

### smartalex\_get\_contact

Get a single contact by UUID. Returns all fields including tags and engagement history.

Use this when you have a specific contact ID. Use `smartalex_list_contacts` to browse contacts.

**Parameters:**

| Parameter | Type          | Required | Description  |
| --------- | ------------- | -------- | ------------ |
| `id`      | string (UUID) | Yes      | Contact UUID |

**Example usage:**

```
"Show me details for contact a1b2c3d4-..."
```

***

### smartalex\_create\_contact

Create a new contact. Returns the created contact with its UUID.

**Parameters:**

| Parameter    | Type      | Required | Description                                                |
| ------------ | --------- | -------- | ---------------------------------------------------------- |
| `first_name` | string    | Yes      | First name                                                 |
| `last_name`  | string    | No       | Last name                                                  |
| `phone`      | string    | No       | Phone number (E.164 format preferred, e.g. `+14155551234`) |
| `email`      | string    | No       | Email address                                              |
| `company`    | string    | No       | Company name                                               |
| `tags`       | string\[] | No       | Tags for categorization (e.g. `["buyer", "vip"]`)          |
| `status`     | string    | No       | Contact status (e.g. `active`, `inactive`)                 |

**Example usage:**

```
"Add a contact John Doe, john@acme.com, +1 555 987 6543"
"Create contact Jane Smith at Acme Corp, tag as enterprise"
```

***

### smartalex\_update\_contact

Update an existing contact. Only provided fields are changed (partial update). Returns the updated contact.

**Parameters:**

| Parameter    | Type          | Required | Description                   |
| ------------ | ------------- | -------- | ----------------------------- |
| `id`         | string (UUID) | Yes      | Contact UUID to update        |
| `first_name` | string        | No       | First name                    |
| `last_name`  | string        | No       | Last name                     |
| `phone`      | string        | No       | Phone number                  |
| `email`      | string        | No       | Email address                 |
| `company`    | string        | No       | Company name                  |
| `tags`       | string\[]     | No       | Tags (replaces existing tags) |
| `status`     | string        | No       | Contact status                |

**Example usage:**

```
"Change John's email to john.doe@newcompany.com"
"Tag contact a1b2... as VIP"
```

***

## Agents

### smartalex\_list\_agents

List all AI voice agents. Returns agent name, language, active status, and creation date. Returns all agents (no pagination).

Use this to browse all agents. Use `smartalex_get_agent` if you have a specific agent ID.

**Parameters:** None

**Example usage:**

```
"Show me my AI agents"
"Which agents are configured?"
```

**Example response:**

```json theme={null}
[
  {
    "id": "d835542e-111b-44ff-b9d8-bf22e9cf7abf",
    "name": "Sales Assistant",
    "voice_provider": "cloud",
    "language": "en",
    "is_active": true,
    "created_at": "2026-02-22T18:10:31+00:00"
  }
]
```

<Note>
  The `voice_provider` field is always returned as `"cloud"`, actual provider details are not exposed through the API for security.
</Note>

***

### smartalex\_get\_agent

Get a single AI voice agent by UUID. Returns full agent configuration.

**Parameters:**

| Parameter | Type          | Required | Description |
| --------- | ------------- | -------- | ----------- |
| `id`      | string (UUID) | Yes      | Agent UUID  |

**Example usage:**

```
"Show me the config for agent d835542e-..."
```

### smartalex\_create\_agent

Create a new AI voice agent. The system scrapes the website (when given), analyzes the business, generates an optimized AI prompt, and deploys the agent. Provide at least a `website_url` **or** a `company_name`.

<Warning>Agent creation takes 30-60 seconds as it scrapes the website and configures the AI voice assistant.</Warning>

**Parameters:**

| Parameter        | Type         | Required | Description                                                                                       |
| ---------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------- |
| `website_url`    | string (URL) | No       | Business website to analyze. Strongly recommended, it enables auto-analysis and a knowledge base. |
| `company_name`   | string       | No       | Company name. Auto-detected from the website if a URL is given; required if it isn't.             |
| `name`           | string       | No       | Agent display name (e.g. "Sarah", "Alex").                                                        |
| `assistant_name` | string       | No       | How the agent introduces itself on calls (defaults to "Alex").                                    |
| `objective`      | string       | No       | What the agent should do on calls (e.g. "Schedule appointments and answer questions").            |
| `first_message`  | string       | No       | Custom greeting message.                                                                          |
| `voice`          | string       | No       | Voice name: Kore (default), Aoede, Puck, Charon, Fenrir, Leda, Orus, Zephyr.                      |
| `accent`         | string       | No       | Voice accent: neutral (default), british, american, australian, south-african, indian.            |

**Example usage:**

```
"Create an agent named Sarah for Bright Smiles Dental from brightsmiles.com that schedules appointments"
```

### smartalex\_update\_agent

Update an existing voice agent's settings. Changes are automatically synced to the live voice platform. Prompt-affecting fields trigger system prompt regeneration.

**Parameters:**

| Parameter               | Type                  | Required | Description                               |
| ----------------------- | --------------------- | -------- | ----------------------------------------- |
| `id`                    | string (UUID)         | Yes      | Agent UUID                                |
| `name`                  | string                | No       | Display name (sidebar/dashboard)          |
| `assistant_name`        | string                | No       | AI name (how the agent introduces itself) |
| `company_name`          | string                | No       | Company name the agent represents         |
| `assistant_personality` | string                | No       | Personality description                   |
| `is_active`             | boolean               | No       | Active/inactive toggle                    |
| `objective`             | string                | No       | What the agent should do on calls         |
| `product_description`   | string                | No       | Product/service description               |
| `first_message`         | string                | No       | Custom greeting message                   |
| `call_direction`        | string                | No       | "inbound", "outbound", or "both"          |
| `language`              | string                | No       | Language code                             |
| `custom_instructions`   | string\[]             | No       | Custom behavior rules                     |
| `background_sound`      | string                | No       | "office" or "off"                         |
| `enabled_tools`         | string\[]             | No       | Tool keys to enable                       |
| `knowledge_item_ids`    | string\[] (UUID)      | No       | KB item UUIDs to link (replaces current)  |
| `phone_number_id`       | string (UUID) or null | No       | Phone number to assign (null to unassign) |

**Example usage:**

```
"Rename agent to Sophie and change the objective to schedule demos"
```

### smartalex\_delete\_agent

Permanently delete a voice agent. This action cannot be undone.

**Parameters:**

| Parameter | Type          | Required | Description |
| --------- | ------------- | -------- | ----------- |
| `id`      | string (UUID) | Yes      | Agent UUID  |

**Example usage:**

```
"Delete the test agent"
```

***

## Phone Numbers

### smartalex\_list\_phone\_numbers

List all active phone numbers with country and agent assignment. Use this to see which numbers are available for campaigns and agents.

**Parameters:** None

**Example usage:**

```
"What phone numbers do I have?"
"List my phone numbers"
```

***

### smartalex\_search\_available\_numbers

Search for available phone numbers to purchase by country. Returns a list of phone numbers that can be bought.

Supported countries: US, CA, GB, AU, NZ, FI, DK, NL, ZA.

**Parameters:**

| Parameter      | Type    | Required | Description                                  |
| -------------- | ------- | -------- | -------------------------------------------- |
| `country_code` | string  | No       | ISO-2 country code (default: "US")           |
| `limit`        | integer | No       | Max results to return (default: 20, max: 50) |

**Example usage:**

```
"Search for available US phone numbers"
"Find 5 phone numbers in the UK"
```

**Example response:**

```json theme={null}
{
  "data": [
    {
      "phone_number": "+14155551234",
      "country": "US",
      "region": "CA",
      "capabilities": ["voice", "sms"]
    }
  ]
}
```

***

### smartalex\_buy\_phone\_number

Purchase a specific phone number for use with campaigns and agents. First number is free on trial; additional numbers cost \~\$1.66/month.

**Parameters:**

| Parameter      | Type   | Required | Description                                        |
| -------------- | ------ | -------- | -------------------------------------------------- |
| `phone_number` | string | Yes      | Phone number in E.164 format (e.g. `+14155551234`) |

**Example usage:**

```
"Buy the number +14155551234"
```

**Example response:**

```json theme={null}
{
  "id": "a1b2c3d4-...",
  "phone_number": "+14155551234",
  "country": "US",
  "status": "active"
}
```

***

## Campaigns

### smartalex\_list\_campaigns

List all voice campaigns. Returns campaign name, mode, status, and agent assignment.

**Parameters:**

| Parameter  | Type    | Required | Description                              |
| ---------- | ------- | -------- | ---------------------------------------- |
| `page`     | integer | No       | Page number (default: 1)                 |
| `per_page` | integer | No       | Results per page (default: 25, max: 100) |

<Note>
  Pagination parameters are accepted but all campaigns are currently returned regardless of page/per\_page values.
</Note>

**Example usage:**

```
"Show me all campaigns"
"What campaigns are running?"
```

**Example response:**

```json theme={null}
[
  {
    "id": "c1d2e3f4-...",
    "name": "Q2 Outreach",
    "status": "active",
    "campaign_mode": "outbound",
    "agent_id": "d835542e-...",
    "created_at": "2026-03-01T09:00:00+00:00"
  }
]
```

***

### smartalex\_create\_campaign

Create a new voice campaign. Optionally assign an AI agent to handle calls.

**Parameters:**

| Parameter         | Type          | Required | Description                                                                       |
| ----------------- | ------------- | -------- | --------------------------------------------------------------------------------- |
| `name`            | string        | Yes      | Campaign name (1-200 characters)                                                  |
| `agent_id`        | string (UUID) | No       | UUID of the AI agent to assign                                                    |
| `objective`       | string        | No       | Call objective, what the agent should do on each call (1-2000 chars)              |
| `description`     | string        | No       | Campaign description (max 500 chars)                                              |
| `campaign_type`   | string        | No       | Campaign type (e.g. `outbound`, `follow-up`)                                      |
| `phone_number_id` | string (UUID) | No       | Phone number to use for outbound calls (from `smartalex_list_phone_numbers`)      |
| `timezone`        | string        | No       | IANA timezone for calling hours (e.g. `America/New_York`, `Europe/London`)        |
| `business_hours`  | object        | No       | Custom calling hours per day, each day has `enabled`, `start`, `end` (24h format) |

<Note>
  Before creating a campaign, always call `smartalex_list_agents` and `smartalex_list_phone_numbers` to let the user pick an agent and phone number.
</Note>

**Example usage:**

```
"Create a new outbound campaign called Q2 Outreach with agent d835542e-..."
```

### smartalex\_get\_campaign

Get a single campaign by UUID. Returns full details including status, objective, contact counts, and call statistics.

**Parameters:**

| Parameter | Type          | Required | Description   |
| --------- | ------------- | -------- | ------------- |
| `id`      | string (UUID) | Yes      | Campaign UUID |

**Example usage:**

```
"Show me the details for campaign c1d2e3f4-..."
```

### smartalex\_add\_contacts\_to\_campaign

Add one or more contacts to a campaign. Contacts are queued for calling when the campaign starts. Duplicates are automatically skipped.

**Parameters:**

| Parameter     | Type             | Required | Description                               |
| ------------- | ---------------- | -------- | ----------------------------------------- |
| `campaign_id` | string (UUID)    | Yes      | Campaign UUID                             |
| `contact_ids` | string\[] (UUID) | Yes      | Array of contact UUIDs (max 100 per call) |

**Example usage:**

```
"Add contacts John and Sarah to the Q2 Outreach campaign"
```

### smartalex\_start\_campaign

Start a campaign to begin making calls. The campaign must have an agent, an objective, and at least one contact.

**Parameters:**

| Parameter     | Type          | Required | Description            |
| ------------- | ------------- | -------- | ---------------------- |
| `campaign_id` | string (UUID) | Yes      | Campaign UUID to start |

<Note>
  Pre-requisites: The campaign must have an agent assigned, an objective set, contacts added, and a phone number available on the account. Missing requirements return a helpful error message.
</Note>

**Example usage:**

```
"Start the Q2 Outreach campaign"
```

***

## Calls

### smartalex\_list\_calls

List call records with pagination. Returns direction, status, duration, sentiment score, and cost.

Use this to browse call history. Use `smartalex_get_call` if you need the full transcript for a specific call.

**Parameters:**

| Parameter  | Type    | Required | Description                              |
| ---------- | ------- | -------- | ---------------------------------------- |
| `page`     | integer | No       | Page number (default: 1)                 |
| `per_page` | integer | No       | Results per page (default: 25, max: 100) |

**Example usage:**

```
"Show me recent calls"
"Get page 3 of call history"
```

**Example response:**

```json theme={null}
{
  "data": [
    {
      "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
      "contact_id": "a1b2c3d4-...",
      "agent_id": "d835542e-...",
      "direction": "outbound",
      "call_status": "completed",
      "duration_seconds": 185,
      "sentiment": 0.72,
      "cost": 0.39,
      "start_timestamp": "2026-03-17T14:30:00+00:00",
      "end_timestamp": "2026-03-17T14:33:05+00:00"
    }
  ],
  "meta": {
    "total": 243,
    "page": 1,
    "per_page": 25
  }
}
```

***

### smartalex\_get\_call

Get a single call record by UUID. Returns full detail including the conversation transcript, duration, sentiment score, and status.

**Parameters:**

| Parameter | Type          | Required | Description |
| --------- | ------------- | -------- | ----------- |
| `id`      | string (UUID) | Yes      | Call UUID   |

**Example usage:**

```
"Show me the transcript for call f1e2d3c4-..."
"What happened in this call?"
```

***

## Deals

### smartalex\_list\_deals

List all deals in the sales pipeline. Optionally filter by stage.

**Parameters:**

| Parameter  | Type    | Required | Description                              |
| ---------- | ------- | -------- | ---------------------------------------- |
| `stage`    | enum    | No       | Filter by stage (see valid stages below) |
| `page`     | integer | No       | Page number (default: 1)                 |
| `per_page` | integer | No       | Results per page (default: 25, max: 100) |

**Valid stages:** `lead`, `qualified`, `showing`, `offer`, `under_contract`, `closed_won`, `closed_lost`

**Example usage:**

```
"Show me all deals"
"Show deals in offer stage"
"What's in my pipeline?"
```

**Example response:**

```json theme={null}
{
  "data": [
    {
      "id": "b7a4bc72-31e2-48a3-85ac-7f3ea5fcdab2",
      "deal_name": "Acme Corp Enterprise",
      "stage": "offer",
      "deal_value": 7500,
      "commission_earned": null,
      "close_date": null,
      "contact_id": null,
      "assigned_user_id": null,
      "created_at": "2026-03-17T08:08:06+00:00",
      "updated_at": "2026-03-17T08:09:19+00:00"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 25
  }
}
```

***

### smartalex\_create\_deal

Create a new deal in the sales pipeline. Optionally link to a contact and set the initial stage and value.

**Parameters:**

| Parameter    | Type          | Required | Description                      |
| ------------ | ------------- | -------- | -------------------------------- |
| `deal_name`  | string        | Yes      | Deal name                        |
| `stage`      | enum          | No       | Pipeline stage (default: `lead`) |
| `deal_value` | number        | No       | Deal value in dollars            |
| `contact_id` | string (UUID) | No       | UUID of the associated contact   |

**Example usage:**

```
"Create a deal for $50k called Acme Corp"
"Add a qualified deal linked to contact a1b2..."
```

***

### smartalex\_update\_deal

Update an existing deal. Only provided fields are changed. Use to move deals through pipeline stages or update values.

**Parameters:**

| Parameter    | Type          | Required | Description             |
| ------------ | ------------- | -------- | ----------------------- |
| `id`         | string (UUID) | Yes      | Deal UUID to update     |
| `deal_name`  | string        | No       | Deal name               |
| `stage`      | enum          | No       | Pipeline stage          |
| `deal_value` | number        | No       | Deal value in dollars   |
| `contact_id` | string (UUID) | No       | Associated contact UUID |

**Example usage:**

```
"Move deal b7a4bc72-... to closed_won"
"Update deal value to $75,000"
```

***

### smartalex\_delete\_deal

Permanently delete a deal from the pipeline. This action cannot be undone.

**Parameters:**

| Parameter | Type          | Required | Description         |
| --------- | ------------- | -------- | ------------------- |
| `id`      | string (UUID) | Yes      | Deal UUID to delete |

**Example usage:**

```
"Delete deal b7a4bc72-..."
```

**Response:**

```json theme={null}
{
  "deleted": true
}
```

***

## Webhooks

### smartalex\_list\_webhooks

List all active webhook subscriptions. Returns URL, event types, active status, failure count, and last delivery time.

**Parameters:** None

**Example usage:**

```
"Show my webhook subscriptions"
"What webhooks are configured?"
```

**Example response:**

```json theme={null}
[
  {
    "id": "7842bee8-f18d-445d-9451-fa62fbfc3300",
    "url": "https://api.example.com/webhook",
    "description": "CRM sync",
    "event_types": ["call.completed"],
    "is_active": true,
    "failure_count": 0,
    "last_delivered_at": "2026-03-18T11:45:00+00:00",
    "created_at": "2026-03-01T10:00:00+00:00"
  }
]
```

***

### smartalex\_create\_webhook

Create a new webhook subscription. Returns the webhook ID and an HMAC-SHA256 `signing_secret`.

<Warning>
  The `signing_secret` is returned **only once** on creation. Save it immediately, it cannot be retrieved later.
</Warning>

**Parameters:**

| Parameter     | Type         | Required | Description                           |
| ------------- | ------------ | -------- | ------------------------------------- |
| `url`         | string (URL) | Yes      | Webhook endpoint URL (HTTPS required) |
| `event_types` | string\[]    | Yes      | Event types to subscribe to           |
| `description` | string       | No       | Human-readable description            |

**Available event types:**

| Event                | Description                      |
| -------------------- | -------------------------------- |
| `call.completed`     | A call has ended                 |
| `call.started`       | A call has started               |
| `deal.stage_changed` | A deal moved to a new stage      |
| `contact.created`    | A new contact was created        |
| `contact.updated`    | A contact was updated            |
| `campaign.started`   | A campaign was activated         |
| `campaign.completed` | A campaign finished all contacts |

**Example usage:**

```
"Subscribe to call events at https://example.com/webhook"
```

**Example response:**

```json theme={null}
{
  "id": "7842bee8-f18d-445d-9451-fa62fbfc3300",
  "url": "https://example.com/webhook",
  "description": "Call notifications",
  "event_types": ["call.completed"],
  "is_active": true,
  "created_at": "2026-03-23T12:27:15+00:00",
  "signing_secret": "a6e1738893513ff5a4a72fba583aa30ba3f3c1a8..."
}
```

***

### smartalex\_delete\_webhook

Unregister a webhook subscription. The endpoint will stop receiving events immediately. This action cannot be undone.

**Parameters:**

| Parameter | Type          | Required | Description            |
| --------- | ------------- | -------- | ---------------------- |
| `id`      | string (UUID) | Yes      | Webhook UUID to delete |

**Example usage:**

```
"Remove webhook 7842bee8-..."
```

**Response:**

```json theme={null}
{
  "deleted": true
}
```

***

## Platform & Widgets

### smartalex\_get\_widget\_install\_code

Get the SmartAlex chat/voice widget installation code for the current workspace. Returns a ready-to-paste HTML `<script>` tag plus platform-specific variants and a short install guide.

**Parameters:** None

**Example usage:**

```
"Give me the widget code for my site"
"How do I add the chat widget to WordPress?"
"Embed code for React"
```

**Returns:**

| Field          | Description                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| `install_code` | Ready-to-paste HTML `<script>` tag. Drop it inside `<head>` (or just before `</body>`).                   |
| `snippets`     | Platform variants: HTML, React (react-helmet), WordPress (`functions.php`), and Shopify (`theme.liquid`). |
| `instructions` | A 3-step install guide.                                                                                   |

### smartalex\_get\_platform\_status

Check SmartAlex platform health and get usage statistics for the current workspace.

**Parameters:** None

**Example usage:**

```
"How's my account doing?"
"Show me platform stats"
"Is SmartAlex working?"
```

**Example response:**

```json theme={null}
{
  "status": "operational",
  "version": "1.0.0",
  "stats": {
    "total_contacts": 21,
    "total_campaigns": 1,
    "total_calls": 243,
    "total_deals": 1
  }
}
```

***

## Tool Annotations

All tools include MCP annotations that help AI clients understand tool behavior:

| Annotation              | Description                 | Tools                                           |
| ----------------------- | --------------------------- | ----------------------------------------------- |
| `readOnlyHint: true`    | Does not modify data        | All list/get tools, platform status             |
| `destructiveHint: true` | Permanently removes data    | `delete_agent`, `delete_deal`, `delete_webhook` |
| `idempotentHint: true`  | Same args = same result     | `update_contact`, `update_agent`, `update_deal` |
| `openWorldHint: true`   | Interacts with external API | All tools                                       |

***

## Related Pages

* [MCP Overview](/mcp/overview), Architecture, resources, prompts, and workflows
* [Getting Started](/mcp/getting-started), Connect SmartAlex to your AI assistant in 2 minutes
* [Error Reference](/mcp/errors), Error codes and troubleshooting