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:

{
  "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:

[
  {
    "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"
  }
]

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

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.

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

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:

{
  "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:

{
  "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)

Pagination parameters are accepted but all campaigns are currently returned regardless of page/per_page values.

Example usage:

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

Example response:

[
  {
    "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)

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

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

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.

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:

{
  "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:

{
  "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:

{
  "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:

[
  {
    "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.

The signing_secret is returned only once on creation. Save it immediately, it cannot be retrieved later.

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:

{
  "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:

{
  "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:

{
  "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

MCP Overview, Architecture, resources, prompts, and workflows
Getting Started, Connect SmartAlex to your AI assistant in 2 minutes
Error Reference, Error codes and troubleshooting

​MCP Tools Reference

​Contacts

​smartalex_list_contacts

​smartalex_get_contact

​smartalex_create_contact

​smartalex_update_contact

​Agents

​smartalex_list_agents

​smartalex_get_agent

​smartalex_create_agent

​smartalex_update_agent

​smartalex_delete_agent

​Phone Numbers

​smartalex_list_phone_numbers

​smartalex_search_available_numbers

​smartalex_buy_phone_number

​Campaigns

​smartalex_list_campaigns

​smartalex_create_campaign

​smartalex_get_campaign

​smartalex_add_contacts_to_campaign

​smartalex_start_campaign

​Calls

​smartalex_list_calls

​smartalex_get_call

​Deals

​smartalex_list_deals

​smartalex_create_deal

​smartalex_update_deal

​smartalex_delete_deal

​Webhooks

​smartalex_list_webhooks

​smartalex_create_webhook

​smartalex_delete_webhook

​Platform & Widgets

​smartalex_get_widget_install_code

​smartalex_get_platform_status

​Tool Annotations

​Related Pages

MCP Tools Reference

Contacts

smartalex_list_contacts

smartalex_get_contact

smartalex_create_contact

smartalex_update_contact

Agents

smartalex_list_agents

smartalex_get_agent

smartalex_create_agent

smartalex_update_agent

smartalex_delete_agent

Phone Numbers

smartalex_list_phone_numbers

smartalex_search_available_numbers

smartalex_buy_phone_number

Campaigns

smartalex_list_campaigns

smartalex_create_campaign

smartalex_get_campaign

smartalex_add_contacts_to_campaign

smartalex_start_campaign

Calls

smartalex_list_calls

smartalex_get_call

Deals

smartalex_list_deals

smartalex_create_deal

smartalex_update_deal

smartalex_delete_deal

Webhooks

smartalex_list_webhooks

smartalex_create_webhook

smartalex_delete_webhook

Platform & Widgets

smartalex_get_widget_install_code

smartalex_get_platform_status

Tool Annotations

Related Pages