AI agents and MCP
An AI agent can set up and run Allerto on its own: read the agent schema, write an agent, test it with test numbers, and place calls once you confirm. Four entry points, all generated from the same schemas as the API:
| Entry point | URL | Use it for |
|---|---|---|
| MCP server | https://api.allerto.cloud/mcp | Claude, Cursor, and any MCP client |
| OpenAPI 3.1 | https://api.allerto.cloud/v1/openapi.json | Frameworks that turn an API into tools |
| llms.txt | https://api.allerto.cloud/llms.txt | Pointing a model at these docs |
| Full text | https://api.allerto.cloud/llms-full.txt | All docs in one file |
Connect an MCP client
The server speaks Streamable HTTP, statelessly, and authenticates with an API key. Give an AI agent a test key first.
Claude Code:
claude mcp add --transport http allerto https://api.allerto.cloud/mcp \
--header "Authorization: Bearer alt_test_…"
Clients that take a JSON configuration (Claude Desktop, Cursor, …):
{
"mcpServers": {
"allerto": {
"url": "https://api.allerto.cloud/mcp",
"headers": { "Authorization": "Bearer alt_test_…" }
}
}
}
Clients that only run local commands can use the CLI as a stdio bridge (it uses the key saved by allerto login):
{ "mcpServers": { "allerto": { "command": "allerto", "args": ["mcp"] } } }
Tools
| Tool | What it does | Effect |
|---|---|---|
get_agent_schema | JSON Schema of the agent document, with every field and default. Read it before creating or editing an agent. | read-only |
get_account | The account this API key belongs to and whether it is in live or test mode. | read-only |
list_agents | List inbound and outbound agents with their draft, published version and numbers. | read-only |
get_agent | Get one agent: draft, revision (needed to save or publish), published version. | read-only |
validate_agent | Check an agent document against every rule without saving it. | read-only |
create_agent | Create an agent as a draft. It does nothing until published. | writes |
save_agent_draft | Replace the draft of an agent. Pass the current revision from get_agent. | writes |
publish_agent | Publish the draft as a new version. From then on real calls use it: confirm with the user first. | real-world effect |
set_agent_mcp_token | Store the bearer token Allerto sends to the agent's MCP server (mcp.url). It is encrypted and never returned. Pass token null to remove it. | writes |
test_agent_mcp | Connect to the MCP server of the agent's draft (or of the given config) and list the tools the agent would get during calls, each marked read or action. Actions run only after the caller's explicit yes. Tools need model gemini-3.8-live. | read-only |
preview_agent | Show the first sentence and the full prompt with example or given inputs. No call is placed. | read-only |
place_call | Queue an outbound call with an outbound agent. With a live key this phones a real person: confirm with the user first. With a test key use +390000000001 (completed), …02 (no answer), …03 (busy), …04 (voicemail), …05 (callback requested), …06 (do not call), …07 (wrong person). | real-world effect |
list_calls | Calls in both directions, newest first, with outcome and result. | read-only |
get_call | One call with status, outcome, callback time and extracted result. | read-only |
get_call_transcript | The transcript of a call (agent and person turns). | read-only |
cancel_call | Cancel an outbound call that has not started yet. | real-world effect |
create_campaign | Queue calls to many contacts with one outbound agent. All contacts are validated first; nothing is queued if one is invalid. Live keys phone real people: confirm with the user first. | real-world effect |
get_campaign | Campaign status and counts by status and outcome. | read-only |
list_suppressions | Numbers that must not be called. | read-only |
add_suppression | Never call this number again from this account. | writes |
An agent on gemini-3.8-live can also use the tools of your MCP server while it is on the phone: set mcp.url in the agent, store the token with set_agent_mcp_token and check the connection with test_agent_mcp. See Tools during calls.
Tools with real-world effects are annotated destructiveHint: true so clients ask for confirmation. With a live key, place_call and create_campaign phone real people.
Suggested prompt
Using the Allerto tools, create an outbound agent that reminds tenants about an unpaid instalment. Read
get_agent_schemafirst. Validate it, publish it, then place test calls to +390000000001 and +390000000005 and tell me the outcomes.
Why this is safe to hand to an agent
- Test keys cannot phone anyone; live keys can be revoked instantly in the console.
- Every
POSTaccepts an idempotency key (idempotency_keyin MCP tools): retrying never calls twice. - Errors carry a stable
codeand the offendingpath, so the agent can correct itself. - Platform rules apply to every agent, whatever instructions it was given.