Integration Guide

Give your AI agent a phone number. Register, get a token, send your first message, go live.

1. Quick Start (5 Steps)

Install & Run

git clone https://github.com/elrad/butt-dial-mcp.git
cd butt-dial-mcp
npm install && cp .env.example .env
npm run build && node dist/index.js

Register

Visit http://localhost:3100/auth/login → Register. Verify with the 6-digit code (printed to console in demo mode).

Get Your API Token

Go to /admin. Your API token is at the top of the dashboard. Click Copy.

Send Your First Message

curl -X POST http://localhost:3100/api/v1/send-message \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"agentId":"test-agent-001","to":"+15559876543","body":"Hello!","channel":"sms"}'

Check for Waiting Messages

curl http://localhost:3100/api/v1/waiting-messages?agentId=test-agent-001 \
-H "Authorization: Bearer YOUR_TOKEN"

This returns any messages that couldn't be delivered while your agent was offline. Fetching acknowledges them automatically. If an LLM key is configured, sandbox sends also generate a simulated reply after ~2 seconds.

2. Authentication

REST: Authorization: Bearer YOUR_TOKEN

MCP: GET /sse?token=YOUR_TOKEN

3. Sandbox Mode

New accounts start in sandbox. All API calls work with mock providers — no real messages, no costs.

LLM-Powered Replies: If ANTHROPIC_API_KEY, OPENAI_API_KEY, or SANDBOX_LLM_ENDPOINT is set, sandbox sends generate a simulated inbound reply after ~2 seconds. Set SANDBOX_LLM_ENABLED=false to disable.

4. REST API

All endpoints at /api/v1/. Interactive docs at /admin#docs.

# SMS
curl -X POST /api/v1/send-message -d '{"agentId":"bot","to":"+15559876543","body":"Hi","channel":"sms"}'

Email
curl -X POST /api/v1/send-message -d '{"agentId":"bot","to":"user@example.com","body":"Hi","channel":"email","subject":"Hello"}'

Voice call
curl -X POST /api/v1/make-call -d '{"agentId":"bot","to":"+15559876543","greeting":"Hello!"}'

Waiting messages (dead letters)
curl /api/v1/waiting-messages?agentId=bot

Provision agent
curl -X POST /api/v1/provision -d '{"agentId":"bot","displayName":"My Bot","capabilities":["sms","voice"]}'

5. MCP Connection

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const transport = new SSEClientTransport(
new URL("http://localhost:3100/sse?token=YOUR_TOKEN")
);
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const result = await client.callTool({
name: "comms_send_message",
arguments: { agentId: "my-agent", to: "+15559876543", body: "Hello!", channel: "sms" }
});

Claude Desktop / Cursor config:

{ "mcpServers": { "butt-dial": { "url": "http://localhost:3100/sse?token=TOKEN" } } }

6. Channels

7. Going Live

1. Add real provider credentials (Settings tab or .env)
2. Set DEMO_MODE=false
3. Set public WEBHOOK_BASE_URL
4. Provision agent with real channels
5. Real messages flow

Community/enterprise editions auto-approve accounts. SaaS requires admin review.

8. Troubleshooting

Full guide: /api/v1/integration-guide (raw markdown) or docs.