Build a Twilio Voice MCP Server for Agentic Outbound Calls & IVR Automation in 2026

By Deepak Bagada, CEO at SaaSNext & Principal AI Architect.

August 2026 is the month agents started making real phone calls. Google shipped consumer agents that dial stores to check inventory, enterprise AI receptionists are deployed at scale, and the entire industry converged on the same conclusion: the phone network is the last integration that matters, and agents are finally allowed to use it. For developers, that shift lands as an API problem: Twilio is the telephony layer behind most of it, and an MCP server is the cleanest way to hand Twilio's power to an agent — place a call, read its status, send DTMF tones, stream audio, and pull a transcript — all as typed, auditable tools.

This guide builds a production Twilio Voice MCP server in Python with FastMCP: outbound call placement, call status and event history, DTMF sending, media stream capture for live ASR, and call termination, secured with the account SID and auth token injected via environment variables and guarded by an outbound-call budget. It pairs with the outbound voice workflow in our AI workflows library, and it follows the security discipline of every server in the MCP directory.

Server Design Overview

graph TD
  A[Agent] --> M[Twilio Voice MCP Server]
  M --> T1[make_call]
  M --> T2[get_call_status]
  M --> T3[send_dtmf]
  M --> T4[start_media_stream]
  M --> T5[end_call]
  T1 --> TW[Twilio API]
  T2 --> TW
  T3 --> TW
  T4 --> TW
  T5 --> TW
  TW --> K[Account SID + Auth Token]
  M --> L[Call Budget + Audit Log]

The server wraps Twilio's Programmable Voice in a small, typed surface. Placing calls is the headline tool — with an explicit outbound budget so an agent cannot dial the world — and the rest are the controls agents need to navigate a live call: status checks, DTMF, media streaming, and hang-up. Every tool returns the call SID and status so the agent can thread the call through its own state machine.

Part 1 — Authentication and setup

.env

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_FROM_NUMBER=+15551234567
TWILIO_API_BASE=https://api.twilio.com/2010-04-01
MEDIA_STREAM_URL=wss://voice-agent.example.com/stream
OUTBOUND_BUDGET_PER_SESSION=25
AUDIT_LOG=./audit.jsonl

auth.py

import os, base64, json, time

# Twilio uses HTTP Basic auth: Account SID as username, Auth Token as password.
def basic_auth() -> str:
    raw = f"{os.environ['TWILIO_ACCOUNT_SID']}:{os.environ['TWILIO_AUTH_TOKEN']}"
    return "Basic " + base64.b64encode(raw.encode()).decode()

def audit(tool: str, meta: dict) -> None:
    line = json.dumps({"ts": time.time(), "tool": tool, **meta})
    with open(os.environ["AUDIT_LOG"], "a") as f:
        f.write(line + "
")

def call_budget_ok() -> bool:
    return call_count() < int(os.environ["OUTBOUND_BUDGET_PER_SESSION"])

The Twilio auth token is a full-account credential — the MCP equivalent of a root key — so it lives only in the environment, never in source or client config, and the server enforces an outbound-call budget per session. Every tool invocation writes an audit line, because when an agent can dial real phone numbers, every dial needs to be answerable: who, what number, when, and why.

Part 2 — The FastMCP server

server.py

import os, httpx
from fastmcp import FastMCP

server = FastMCP(name="twilio-voice", version="1.3.0")
BASE = os.environ["TWILIO_API_BASE"]
SID = os.environ["TWILIO_ACCOUNT_SID"]

@server.tool(description="Place an outbound phone call to a number.")
def make_call(to: str, reason: str, twiml_url: str | None = None) -> dict:
    if not call_budget_ok():
        raise ValueError("outbound call budget exceeded for this session")
    if not reason.strip():
        raise ValueError("reason is required: every dial must be explainable")
    data = {"To": to, "From": os.environ["TWILIO_FROM_NUMBER"],
            "Url": twiml_url or f"{os.environ['MEDIA_STREAM_URL']}/twiml"}
    r = httpx.post(f"{BASE}/Accounts/{SID}/Calls.json",
                   data=data, headers={"Authorization": basic_auth()}, timeout=20)
    r.raise_for_status()
    audit("make_call", {"to": to, "reason": reason})
    return {"call_sid": r.json()["sid"], "status": r.json()["status"]}

@server.tool(description="Get the live status of a call.")
def get_call_status(call_sid: str) -> dict:
    r = httpx.get(f"{BASE}/Accounts/{SID}/Calls/{call_sid}.json",
                  headers={"Authorization": basic_auth()}, timeout=15)
    r.raise_for_status()
    j = r.json()
    audit("get_call_status", {"call_sid": call_sid})
    return {"call_sid": call_sid, "status": j["status"],
            "duration": j.get("duration"), "direction": j.get("direction")}

@server.tool(description="Send DTMF keypad tones on a live call.")
def send_dtmf(call_sid: str, digits: str) -> dict:
    r = httpx.post(f"{BASE}/Accounts/{SID}/Calls/{call_sid}.json",
                   data={"Twiml": f"<Response><Play digits="w{','.join(digits)}" /></Response>"},
                   headers={"Authorization": basic_auth()}, timeout=15)
    r.raise_for_status()
    audit("send_dtmf", {"call_sid": call_sid, "digits": digits})
    return {"call_sid": call_sid, "status": "dtmf_sent"}

The three core tools cover the lifecycle agents need most: dial with a reason, check status, and press keys. make_call is the guarded write — it refuses to dial without a reason and consumes the outbound budget. send_dtmf is the tool that makes IVR navigation possible: the agent hears a menu, decides the option, and presses the keys through this tool. Every call returns the SID, which the agent threads through its state machine as it decides the next action.

Part 3 — Media streaming and call control

media.py

import os, httpx, websockets

@server.tool(description="Start a Twilio Media Stream to the configured WebSocket for live ASR.")
def start_media_stream(call_sid: str) -> dict:
    # TwiML with <Connect><Stream> sends live audio to our WebSocket
    twiml = ("<Response><Connect><Stream url="%s" /></Connect></Response>"
             % os.environ["MEDIA_STREAM_URL"])
    r = httpx.post(f"{BASE}/Accounts/{SID}/Calls/{call_sid}.json",
                   data={"Twiml": twiml},
                   headers={"Authorization": basic_auth()}, timeout=15)
    r.raise_for_status()
    audit("start_media_stream", {"call_sid": call_sid})
    return {"call_sid": call_sid, "stream": "connected"}

@server.tool(description="Hang up an active call.")
def end_call(call_sid: str) -> dict:
    r = httpx.post(f"{BASE}/Accounts/{SID}/Calls/{call_sid}.json",
                   data={"Status": "completed"},
                   headers={"Authorization": basic_auth()}, timeout=15)
    r.raise_for_status()
    audit("end_call", {"call_sid": call_sid})
    return {"call_sid": call_sid, "status": "completed"}

Media streams are what turn a phone call into an agent conversation. start_media_stream rewires the live call's audio into the configured WebSocket, where a streaming speech-to-text engine produces the transcript the agent reasons over — the same primitive the outbound voice workflow in our AI workflows library uses to navigate IVR menus and monitor holds. end_call is the clean termination: explicit, audited, and always available to an agent that decides the task is done or the call is unwinnable.

Part 4 — Client configuration and launch

mcpServers config

{
  "mcpServers": {
    "twilio-voice": {
      "command": "python",
      "args": ["-m", "twilio_voice_mcp"],
      "env": {
        "TWILIO_ACCOUNT_SID": "${TWILIO_ACCOUNT_SID}",
        "TWILIO_AUTH_TOKEN": "${TWILIO_AUTH_TOKEN}",
        "TWILIO_FROM_NUMBER": "+15551234567",
        "MEDIA_STREAM_URL": "wss://voice-agent.example.com/stream",
        "OUTBOUND_BUDGET_PER_SESSION": "25"
      }
    }
  }
}

main.py

from server import server
import media  # registers media stream + end_call tools

if __name__ == "__main__":
    server.run(transport="stdio")  # desktop; or transport="http" for remote

The mcpServers block wires the server into any MCP client; the env block injects credentials from your shell environment, never literals. The outbound budget travels with the config so every deployment carries its own dialing cap. stdio serves desktop agents; HTTP serves remote or stateless MCP 2026-07-28 deployments, where the Twilio credentials stay server-side behind the gateway and the WebSocket URL is reachable by the media stream. Both transports are covered in the MCP directory.

Security & governance checklist

1. Treat the auth token as root. Twilio credentials are full-account — environment-only, never in source or client config literals.
2. Outbound budget per session. make_call consumes a bounded budget and refuses to dial without a reason string.
3. Audit every dial. JSONL audit with call SID, target, reason, and timestamp — every dial is answerable.
4. Idempotent call control. Status checks and hang-up are safe to retry; DTMF should only be sent on confirmed state.
5. Pick transport by deployment. stdio for desktop agents; HTTP behind a gateway for remote fleets.

Frequently Asked Questions

Q: Why expose Twilio through MCP instead of calling the REST API directly?

A: Because an agent needs the whole call lifecycle as tools — dial, status, DTMF, media stream, hang-up — with typed schemas, a shared audit trail, and one place where the outbound budget is enforced. MCP makes Twilio a first-class tool for any agent client.

Q: How is Twilio authentication handled?

A: Twilio uses HTTP Basic auth with the Account SID as username and the Auth Token as password. Both live in environment variables only, and the token should be treated with the same care as a root credential.

Q: How does the agent navigate an IVR through this server?

A: The agent hears the menu through the media stream transcript, picks an option, and calls send_dtmf with the keypad digits — or speaks the option if the TwiML Gather flow is configured for speech. The call SID threads through the whole interaction.

Q: What is the outbound budget for?

A: It caps how many calls a single agent session can place, so a runaway loop cannot dial the world. Every call also requires a reason string, which becomes part of the audit record.

Q: Can this server run for remote agents?

A: Yes. The HTTP transport serves the same tools for remote or stateless MCP 2026-07-28 deployments, with Twilio credentials staying server-side behind a gateway and the media-stream WebSocket URL reachable by Twilio.