Twilio MCP server: what the official options do, and how to get an AI on a call

Search for "Twilio MCP" today and you will find two different official projects with almost the same name. One is a hosted server at mcp.twilio.com/docs that Twilio launched in May 2026. It helps a coding agent search Twilio's documentation and API specs. It cannot send a text or place a call. The other is @twilio-alpha/mcp, an older open-source project that runs on your machine and turns Twilio's REST API into hundreds of tools. That one can buy numbers, send SMS and create calls. It is labelled a proof of concept, and its latest release is from July 2025.

Neither one puts an AI on a live phone call. If your agent calls Twilio's create-call tool, Twilio dials the number and runs whatever instructions you attached, usually a line of text-to-speech. The model that asked for the call never hears the other person. Getting it to hold a conversation is a separate build.

This guide covers both servers: how to install each one, what it is good for, and what to watch out for. Then it walks through what an AI phone call over Twilio actually takes, and where a hosted phone-call MCP server fits instead. Everything was checked against Twilio's docs, GitHub, npm and pricing pages on October 19, 2026, and we listed the tools on both servers ourselves that day.

Two things called "Twilio MCP"

Twilio's own docs now use "the Twilio MCP server" for the hosted one. The Claude connector and the twilio-developer-kit plugin for Claude Code and Cursor install the hosted one too. Many older tutorials and MCP directory listings for "Twilio MCP server" describe the Alpha project. Know which one a guide means before you follow it.

The hosted Twilio MCP server (docs search)

Twilio announced it at SIGNAL on May 7, 2026, alongside Twilio Skills, and both are in Public Beta. The docs page says it gives coding agents "direct, structured access to Twilio's full API surface", over 1,800 endpoints across more than 30 products. In practice that access means two tools:

• twilio__search takes a plain-language question and returns ranked API operations, doc articles and IDs.
• twilio__retrieve returns the full request and response schema for an operation.

The index covers Twilio's public OpenAPI specs, its docs and support articles, and the SendGrid and Segment docs. The limitations section is blunt: "Read-only: The server provides API search and documentation retrieval. It does not execute API calls on your behalf." When we called tools/list on it, those were the only two tools, and both carried readOnlyHint: true. Tools that can call Twilio's APIs with OAuth sign-in are on the "what's next" list, so they have not shipped yet.

Twilio's partner blog post about the Claude connector describes it more broadly, as "secure, real-time access to Twilio's communications platform". Go by the docs. Today the connector reads documentation.

Setup takes one command because there is nothing to authenticate. From Twilio's docs:

# Claude Code
claude mcp add --transport http twilio-docs https://mcp.twilio.com/docs

# Codex
codex mcp add twilio-docs --url https://mcp.twilio.com/docs

Cursor takes the same URL in mcp.json:

{
  "mcpServers": {
    "twilio-docs": { "url": "https://mcp.twilio.com/docs" }
  }
}

In Claude you can search for "Twilio" in the connectors directory instead. If you are new to adding remote servers to a client, our Claude Code MCP guide covers scopes and how to check the tools actually loaded.

Is it worth installing? If you write Twilio code with an agent, yes. It is free, it cannot touch your account, and it saves the model from guessing parameter names from memory. Just don't expect it to do anything on the phone network.

The Twilio Alpha MCP server (the one that can act)

twilio-labs/mcp came out of Twilio's Emerging Tech team in March 2025. It is a monorepo with two packages: @twilio-alpha/openapi-mcp-server, which turns any OpenAPI spec into MCP tools, and @twilio-alpha/mcp, which does that for Twilio's public API. The package README opens with "This is a Proof of Concept (PoC) project". Both packages are at 0.7.0, published to npm on July 7, 2025, and nothing newer has shipped since. It still gets used: about 5,900 npm downloads in the 30 days to October 18, 2026.

The README's config for Claude Desktop and similar clients:

{
  "mcpServers": {
    "twilio": {
      "command": "npx",
      "args": [
        "-y",
        "@twilio-alpha/mcp",
        "YOUR_ACCOUNT_SID/YOUR_API_KEY:YOUR_API_SECRET"
      ]
    }
  }
}

Three things to know before you paste that in.

It loads a lot of tools

By Twilio Alpha's count, Twilio has nearly 2,000 API operations, and loading all of them would blow through most models' context windows. So the server makes you choose with --services (a spec file name from twilio-oai, such as twilio_api_v2010) and --tags (individual resource groups). If you pass neither, it loads only twilio_api_v2010, the core API. That "only" is still big. When we ran it, the default setup listed 197 tools, and the tool list came to about 317 KB of JSON. By a rough four-characters-per-token estimate, that is around 80,000 tokens of tool definitions before your first message. Narrow it down with tags:

"args": ["-y", "@twilio-alpha/mcp", "YOUR_ACCOUNT_SID/YOUR_API_KEY:YOUR_API_SECRET",
         "--tags", "Api20100401IncomingPhoneNumber,StudioV2Flow"]

The secret lives in your config file

Credentials go in as a single argument, ACxxx/SKxxx:secret, so the API secret sits in plain text in your client's JSON config. Create a dedicated API key for it, not your main credentials, so you can revoke it on its own. Twilio's Functions-hosted version of the same server (the mcp-server template in twilio-labs/function-templates) adds two more rules worth following anywhere: "Always set your MCP client to require tool approval" and "Use scoped permissions for your Twilio API Key."

Twilio says to run it alone

The README carries this warning: "the ETI team advises users of Twilio MCP servers to avoid installing or running any community MCP servers alongside our official ones." The reason is injection. A tool result from some other server can carry text that steers the model into calling your Twilio tools. With a server that can send messages and buy numbers on your account, that risk is real.

One more trap. Some MCP directories list an "official" install command of npx -y @twilio/mcp or @twilio/mcp-server. Neither package exists on npm. The real package is @twilio-alpha/mcp.

What happens when your agent calls CreateCall

This is where most people's expectations break. The Alpha server's TwilioApiV2010--CreateCall tool is a thin wrapper around Twilio's Calls API. Its required fields are To and From, and the call also needs instructions: a Twiml string of up to 4,000 characters, a Url that returns TwiML, or an ApplicationSid. Twilio's own quickstart example is this:

twiml="<Response><Say>Ahoy, World</Say></Response>"

So when you tell Claude "call the dentist and move my appointment" with this server loaded, the best it can do is make Twilio dial the dentist and read out a fixed message. When the receptionist answers and asks which day works, nobody is listening. The model sent one API request and got back a call SID. To find out what happened, it has to fetch the call record later, which tells it the status and duration. Unless you also set up recording and transcription, nothing records what was said.

Two more constraints come from Twilio's side:

• Caller ID. From "must be a Twilio number or a Verified outgoing caller id for your account." You can verify your own mobile number and show that, or rent a Twilio number. A local US number costs $1.15 a month.
• Trial accounts. On a trial you can only call numbers you have verified, up to five of them, and only within your own country. Some TwiML verbs are blocked.

Getting an AI to actually talk on a Twilio call

Twilio sells the pieces for a real conversation. You assemble them:

• ConversationRelay handles speech-to-text and text-to-speech and sends text to your app over a WebSocket. You "bring your own large language model". You put a <ConversationRelay> noun inside <Connect> in your TwiML, point its url at a WebSocket server that you host, and that server calls the model and sends replies back. You also have to complete onboarding and accept Twilio's AI/ML features addendum first.
• Media Streams gives you the raw call audio over a WebSocket, in both directions if you use <Connect><Stream>. You handle speech yourself, for example by bridging to a speech-to-speech model.
• OpenAI Realtime over SIP. Twilio's Elastic SIP Trunking can route a call to OpenAI's Realtime SIP endpoint. You still run a webhook server that accepts the call and configures the session. The documented setup is for incoming calls.

The community has wrapped some of this back into MCP. voice-call-mcp-server lets Claude start a call that is handled by OpenAI's Realtime model, using ngrok to give Twilio a public URL to reach your laptop. phony does something similar with IVR keypress support and a MongoDB store. Both are worth reading to see how the pieces fit, and both leave you running the infrastructure, holding the API keys and owning the compliance.

The telephony is cheap. Twilio's US list prices, current as of August 2026, are $0.014 a minute for outbound calls and $0.07 a minute for ConversationRelay. A five-minute call comes to about $0.42 before the language model's own cost. The work is the rest: a public WebSocket server, turn-taking, hold music, phone menus, voicemail detection, transcripts, and a way to get the result back to the agent that asked. Our guide to building an AI voice agent maps the build options in more detail, and which voice AI APIs can call a cell phone compares the platforms that do the dialing.

The rules come with the phone line

Whichever way you build it, US law treats an AI voice as an artificial voice. The FCC's February 2024 declaratory ruling says calls using "AI technologies that generate human voices" fall under the TCPA and "require the prior express consent of the called party", absent an emergency or an exemption. FCC rules also say artificial-voice messages must state who is responsible for the call at the beginning, and telephone solicitations to homes are limited to 8 a.m. to 9 p.m. in the called party's time zone.

Twilio passes these duties to you. For telemarketing and advertising calls, its Voice Services Policy requires prior consent, identifying yourself at the start of the call, an opt-out mechanism, and respecting do-not-call lists. For all calls, it bans misleading caller ID. Its acceptable use policy lets Twilio suspend accounts that break the rules. None of this is enforced inside the MCP server: if your agent places a call at 10 p.m., the API will place it. This is not legal advice, so check the rules for your own use case.

Where a hosted phone-call MCP server fits

A different design is a remote MCP server built for one job, a phone call, with the voice pipeline and the rules already on the server. That is what we built DialMCP to be, so read this section with that in mind.

You add https://mcp.dialmcp.com/mcp to Claude, ChatGPT, Codex, Cursor or another client, sign in with OAuth, and verify your mobile number by SMS. There is no API key in a config file. The server exposes four tools (tool reference):

• place_call takes a destination number and a plain-language objective, such as "move my cleaning to any weekday afternoon next week". A real-time voice agent holds the conversation, presses keys in phone menus and waits on hold.
• get_call returns the live status and, when the call ends, a transcript, the recording and a structured outcome. Calls run in the background, typically two to five minutes, so a long hold does not trip your client's tool timeout.
• end_call and list_calls stop a call and list recent ones.

The call shows your own verified number, so the person can call you back. The rules a Twilio build leaves to you are built into the server rather than left to your prompts (how DialMCP handles safety). The agent says it is an AI calling on your behalf before anything else, and every transcript is checked for that disclosure after the call. Calls only start between 8 a.m. and 9 p.m. in the destination's time zone. Anyone who says "don't call me again" goes on a permanent list for every user, and each objective is screened before dialing.

The trade-off is control, and it is a real one. DialMCP calls the US and Canada only. It allows one call at a time, three an hour and ten a day per user. It does not send SMS, take inbound calls or run campaigns. It is built for one person's assistant making one errand call, not for a product that calls customers.

Which one should you use?

These are not either-or. A sensible setup for a developer is the hosted Twilio docs server in the coding agent, Twilio itself for anything customer-facing, and a phone-call server in the personal assistant. If you are weighing the general question of when a plain API beats an MCP tool, MCP vs API builds the same phone call both ways.

FAQ

Is there an official Twilio MCP server?

Yes, two. The hosted Twilio MCP server at https://mcp.twilio.com/docs (Public Beta since May 2026) searches Twilio's docs and API specs and is read-only. The older Twilio Alpha project, @twilio-alpha/mcp from twilio-labs/mcp, runs locally and exposes Twilio's REST API as tools. It is a proof of concept, last released as v0.7.0 in July 2025.

Can the Twilio MCP server make phone calls?

The hosted server cannot; it only reads documentation. The Alpha server's CreateCall tool makes Twilio dial a number and run TwiML instructions, such as a text-to-speech message. The AI model is not on the call. For a two-way AI conversation you need ConversationRelay or Media Streams and your own WebSocket server, or a hosted phone-call MCP server.

How do I add Twilio MCP to Claude Code?

For the hosted docs server, run: claude mcp add --transport http twilio-docs https://mcp.twilio.com/docs. No login is needed. For the Alpha server, add an npx command for @twilio-alpha/mcp with your Account SID, API key and secret as the argument, and limit the tools with --services or --tags.

Is Twilio MCP free?

The hosted docs server is free and needs no Twilio account. The Alpha server is free open-source software, but anything billable it does, such as placing calls, sending messages or buying numbers, is charged to your Twilio account at normal rates: in the US, $0.014 a minute for outbound calls and $1.15 a month for a local number, as of August 2026 list prices.

Can I show my own phone number when calling through Twilio?

Yes, if you add it as a verified outgoing caller ID. Twilio's Calls API requires the From number to be a Twilio number or a verified caller ID on your account. Trial accounts can only call up to five verified numbers in their own country.