> ## 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.
# What an AI agent can do with SmartAlex
> An AI agent can operate SmartAlex through its live MCP server: create voice agents, run campaigns, manage contacts, deals, calls and analytics.
**An AI agent does not just read about SmartAlex, it can operate it.** The live SmartAlex MCP server turns any MCP-compatible assistant, including Claude, ChatGPT, Cursor, and Gemini, into a controller for your voice platform: it can create and manage voice agents, run outbound campaigns, manage contacts and a deals pipeline, read call transcripts and analytics, buy phone numbers, and fetch widget install code, all under authenticated, per-workspace access.
Most platforms give an AI agent documentation to read. SmartAlex gives it a set of tools to act with. The Model Context Protocol server is live today, exposing **28 tools, 7 resources, and 5 prompts** across eight domains, so an assistant can carry out real work in your workspace through plain conversation rather than clicking through a dashboard.
The MCP server and Custom HTTP Tools are the live programmatic surfaces today. A public REST API and TypeScript SDK are in private beta and coming soon.
## At a glance
| Domain | What an AI agent can do | Access | Tools |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----- |
| Voice agents | Build an agent from a website URL or a full spec, update it, activate or deactivate, delete, with automatic sync to the live voice platform | Read and write | 5 |
| Contacts | List, look up, create, update, tag and segment the contact database | Read and write | 4 |
| Campaigns | Create outbound campaigns, add contacts, start calling, and track progress | Read and write | 5 |
| Calls | Browse call history and read full transcripts with sentiment and cost | Read only | 2 |
| Deals | Move deals through the sales pipeline from lead to closed | Read and write | 4 |
| Phone numbers | List active numbers, search available numbers by country, and buy one | Read and write | 3 |
| Webhooks | Subscribe to and manage event webhooks for external systems | Read and write | 3 |
| Platform and widgets | Check platform health and usage, and fetch widget install code | Read only | 2 |
**Bottom line:** SmartAlex is one of the few voice platforms an AI agent can run end to end today, through a live MCP server with API-key or OAuth authentication, strict per-workspace isolation, and clear read and write scopes, with a public REST API arriving soon.
## The operating surface
Every tool is prefixed `smartalex_` so it never clashes with other MCP servers, and each one maps to a real operation in your workspace. Grouped by domain, here is the full capability surface an AI agent gets.
### Create and manage voice agents
An agent can stand up a working voice assistant from almost nothing. Give it a website URL and `smartalex_create_agent` scrapes the business, analyzes it, generates an optimized prompt, and deploys a live agent in about 30 to 60 seconds. It can also set the assistant name, objective, first message, voice, and accent. From there it can list agents, read full configuration, update behavior and tools, assign a phone number, toggle active status, and delete an agent. Prompt-affecting changes regenerate the system prompt and sync automatically to the live voice platform.
### Run outbound campaigns
The full outbound loop is available without a dashboard. An agent can create a campaign, set the objective and calling hours with a timezone, add contacts in batches, and start calling. It can read campaign detail including contact counts and call statistics, and check status as calls progress. Before starting, the tools guide the assistant to confirm the campaign has an agent, an objective, contacts, and a phone number, so it fails with a clear message rather than a bad run.
### Manage contacts and deals
An agent can keep your CRM current: list and look up contacts, create new ones with company and tags, and apply partial updates. On the pipeline side it can list deals filtered by stage, create deals with a value and linked contact, move them through stages from `lead` to `closed_won`, and delete them. This lets an assistant turn a call outcome into a pipeline update in the same conversation.
### Read calls and analytics
An agent can browse call history with direction, status, duration, sentiment score, and cost, then pull the full transcript for any single call. The platform status tool returns workspace usage stats (total contacts, campaigns, calls, and deals) alongside a health check, so an assistant can answer "how did last week look" from real data.
### Manage phone numbers
An agent can list the active numbers on the account, search available numbers by country across the supported regions, and buy a specific number in E.164 format. Purchased numbers are immediately usable for campaigns and agent assignment.
### Fetch widget install code
An agent can call `smartalex_get_widget_install_code` to return a ready-to-paste HTML script tag plus platform-specific variants for React, WordPress, and Shopify, with a short install guide. This lets an assistant help a user embed the SmartAlex chat and voice widget on their site without leaving the conversation.
### Set up webhooks
An agent can create event-driven integrations: subscribe an HTTPS endpoint to events such as `call.completed`, `deal.stage_changed`, `contact.created`, and `campaign.completed`, list active subscriptions with their failure counts, and remove a webhook. Each subscription returns an HMAC-SHA256 signing secret once at creation for verifying delivery authenticity.
Beyond the tools, the server ships **7 read-only resources** that give an assistant ambient context about your workspace, and **5 prompts** that are ready-made workflows for campaign strategy, lead qualification, and call analysis.
## Read versus write
Of the 28 tools, half read and half write, which makes it straightforward to grant an AI agent exactly the reach you intend.
| Category | What it covers | Scope required |
| --------------------- | ----------------------------------------------------------------------------- | -------------------------------- |
| Read (14 tools) | Every list and get, number search, platform status, and widget install code | `read` (the default) |
| Write (14 tools) | Create, update, buy a number, add campaign contacts, and start a campaign | `write` |
| Destructive (3 tools) | `smartalex_delete_agent`, `smartalex_delete_deal`, `smartalex_delete_webhook` | `write`, and flagged destructive |
Every tool carries MCP annotations so a well-behaved client knows how to treat it: `readOnlyHint` marks the safe list and get tools, `destructiveHint` marks the three permanent deletes so cautious clients confirm first, and `idempotentHint` marks updates that are safe to retry. A key scoped to `read` that tries to call a write tool is rejected with a `403`, so you can hand a reporting assistant read-only access with confidence.
## The operating contract
An AI agent operates SmartAlex under a clear contract: how it authenticates, what it can reach, and how fast it can go.
### Authentication
The cloud server accepts a **SmartAlex API key** or an **OAuth 2.0** token on the `Authorization: Bearer` header. API keys suit local and scripted clients, while OAuth suits hosted clients that connect by URL and approve in the browser.
| Method | Best for |
| ---------------------------------- | -------------------------------------------------------------------------- |
| API key (`sa_live_` or `sa_test_`) | Local installs over stdio, scripts, and any client where you paste a token |
| OAuth 2.0 (PKCE, `S256`) | Hosted clients such as ChatGPT and Claude that connect by URL |
Keys are generated in the Developer Portal, which requires the Power Tools add-on and a super-admin role on the workspace. A key is shown once at creation; only a hash is stored, so a lost key is regenerated rather than looked up.
### Tenant isolation
This is the guarantee that makes it safe to let an assistant act. Every credential resolves to exactly one workspace. An API key belongs to the workspace it was created in, and an OAuth token resolves to the user's active workspace. The gateway then scopes every read and write to that workspace, so **one credential can never reach another tenant's data**. An AI agent connected to your workspace only ever sees and touches your workspace.
### Rate limits
| Transport | Limit | Keyed by |
| -------------------- | ----------------------- | ---------- |
| Cloud, authenticated | 100 requests per minute | Workspace |
| Public, onboarding | 30 requests per minute | IP address |
Going over returns a `429` with a `Retry-After` header and `X-RateLimit-*` headers, and most clients back off automatically. The public REST path, when it ships, will carry its own per-key limit (default 60 per minute, adjustable at key creation).
### What stays hidden
Provider details are never exposed. Agent records return `voice_provider` as `"cloud"` rather than any underlying vendor, because SmartAlex runs a curated, high-accuracy speech-to-text, language, and text-to-speech stack behind the platform, and keeps it abstracted. Signing secrets and API keys are returned only once, and all traffic is HTTPS.
## Live today, and what is next
The MCP server (cloud and local) and Custom HTTP Tools, which let an agent call your own HTTPS endpoint mid-call, are live in production today.
A public REST API, a TypeScript SDK, and outbound webhook events are in private beta. Contact support for early access.
The practical takeaway: if you want programmatic control of SmartAlex right now, the MCP server is the front door, and it already covers the full operational surface an AI agent needs.
## Connect an agent in two minutes
The fastest path is the hosted cloud endpoint with OAuth, no install and no key to copy:
```bash theme={null}
claude mcp add --transport http smartalex https://api.getsmartalex.com/functions/v1/mcp-server
```
For local clients such as Cursor, VS Code, or Claude Desktop, run the server over stdio with an API key:
```bash theme={null}
export SMARTALEX_API_KEY=sa_live_your_key_here
npx @smartalex/mcp-server
```
Once connected, an assistant can act immediately. Try "show me my SmartAlex contacts", "create an agent for my clinic from example.com", or "start the Q2 outreach campaign", and it will select the right tool and run it against your workspace. The [Getting started guide](/mcp/getting-started) walks through every supported client, and the [tools reference](/mcp/tools-reference) documents each tool's parameters and responses.
## Frequently asked questions
### Can an AI agent create and run a voice agent on SmartAlex?
Yes. Through the MCP server, an assistant calls `smartalex_create_agent` with a website URL or a company name, and SmartAlex analyzes the business, generates a prompt, and deploys a live voice agent in about 30 to 60 seconds. The assistant can then assign a phone number, add the agent to a campaign, add contacts, and start outbound calling, all in one conversation.
### How does SmartAlex keep an AI agent inside its own workspace?
Every credential resolves to exactly one workspace. An API key belongs to the workspace where it was created, and an OAuth token resolves to the user's active workspace. The API gateway scopes every read and write to that workspace, so a connected AI agent can never see or change another tenant's contacts, agents, campaigns, or calls. Isolation is enforced at the gateway, not left to the client.
### Which SmartAlex actions are read-only versus write?
Of the 28 tools, 14 are read-only (all list and get tools, number search, platform status, and widget code) and 14 are write (create, update, buy, add contacts, start, and delete). The default `read` scope grants only the read tools, and write tools require a key with the `write` scope. The three delete tools are additionally flagged destructive so cautious clients confirm before running them.
### Does SmartAlex have a public REST API for AI agents?
A public REST API is in private beta and coming soon, alongside a TypeScript SDK and outbound webhook events. Today the live programmatic surfaces are the MCP server, which covers the full operational surface an agent needs, and Custom HTTP Tools, which let an agent call your own HTTPS endpoint during a call. Contact support if you need REST API early access.
### What can an AI agent not do through SmartAlex?
An agent cannot cross workspace boundaries, cannot see the underlying voice providers (agent records report a generic `cloud` provider), and cannot perform write actions with a read-only key. Requests are rate limited to 100 per minute per workspace, and the three delete tools are flagged destructive so clients can require confirmation. These limits are what make it safe to hand an assistant real access.
## Related
The 28 tools, 7 resources, and 5 prompts, and how the pieces fit together.
Connect Claude, ChatGPT, Cursor, or Gemini to SmartAlex in under two minutes.
Every tool with its parameters, examples, and response shapes.
A plain-language explainer of the Model Context Protocol.