Getting Started

Prerequisites

• Node.js 22+ and npm
• Twilio account — for SMS, voice calls, and WhatsApp
• Resend account (optional) — for email
• ElevenLabs account (optional) — for premium TTS (free Edge TTS is the default)

Installation

git clone https://github.com/elrad/butt-dial-mcp.git
cd butt-dial-mcp
npm install
cp .env.example .env

Configuration

Minimum (Demo Mode)

PORT=3100
DEMO_MODE=true

Demo mode uses mock providers — no real API calls, no costs.

Production

PORT=3100
DEMO_MODE=false

Required for SMS/voice
TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...

Required for email
RESEND_API_KEY=re_...

Optional premium TTS (falls back to free Edge TTS)
ELEVENLABS_API_KEY=sk_...

Security
ORCHESTRATOR_SECURITY_TOKEN=your-secret-token
WEBHOOK_BASE_URL=https://your-domain.com

See .env.example for all available options.

Build & Run

npm run build
npm run seed    # Creates a test agent (test-agent-001)
node dist/index.js

The server starts on port 3100 (default).

Web Setup Wizard

Visit http://localhost:3100/admin/setup for guided configuration:

1. Enter Twilio credentials → click Test Connection → auto-saves on success
2. Enter ElevenLabs key → test → auto-saves
3. Enter Resend key → test → auto-saves
4. Configure server settings (webhook URL, orchestrator token)
5. Set voice defaults (greeting, language, voice ID)

Each card validates credentials live before saving.

Verify

curl http://localhost:3100/health
Returns: {"status":"ok","uptime":...,"version":"0.1.0"}

Expose Webhooks (Development)

For inbound messages and calls to reach your local server, expose it publicly:

ngrok http 3100
Copy the HTTPS URL to WEBHOOK_BASE_URL in .env

Connect an AI Agent

Your AI agent connects via MCP over SSE:

GET http://localhost:3100/sse?token=<agent-security-token>

• token — Security token generated during provisioning
• agentId — Registers the agent session for voice routing and message delivery

Once connected, your MCP client can list and call all available tools. See MCP Tools for the full reference.

Inbound Message Flow

When someone texts, emails, or calls your agent's number:

1. The server receives the webhook from Twilio/Resend/LINE
2. Validates the signature
3. Checks channel blocking — blocked channels are silently dropped
4. Forwards the message to your connected agent session
5. If the agent is offline, stores it in the dead letter queue

When your agent reconnects, call comms_get_waiting_messages to fetch any messages that arrived while offline. Fetching acknowledges them automatically.

For voice calls, the server relays the caller's speech as text to your agent via MCP sampling, and your agent's text response is spoken back to the caller.

Startup Warnings

These are warnings, not errors. The server always starts.