Telephony

You can extend your language models with real-world actions by running a Telephony MCP Server. It exposes tools for making voice calls and sending SMS messages via the Vonage API, letting your LLM applications perform concrete telephony tasks beyond text generation.

How to use

To use this Telephony MCP Server, connect your MCP client or LangChain-based application to the running MCP server. The server provides tools that your LLM can invoke when a user prompt requires real-world actions. For example, your LLM can decide to dial a number or send an SMS by calling the corresponding MCP tool. The two primary tools are voice_call and send_sms. Use these tools to initiate calls or compose and deliver messages, and then handle the results within your LLM’s response.

How to install

Prerequisites: you need Python 3.13 or later and the MCP CLI stack installed (includes FastAPI, httpx, pyjwt, python-dotenv, uvicorn, and pydantic, as listed in your project’s pyproject.toml). You also need Vonage API credentials and a public callback URL for production use.

Install dependencies and set up the server:

pip install -r requirements.txt

Or, if you are using Poetry:

poetry install

Configure environment variables for Vonage and the callback server in a .env file:

VONAGE_API_KEY=your_api_key
VONAGE_API_SECRET=your_api_secret
VONAGE_APPLICATION_ID=your_app_id
VONAGE_PRIVATE_KEY_PATH=path/to/private.key
VONAGE_LVN=your_virtual_number
VONAGE_API_URL=https://api.nexmo.com/v1/calls
VONAGE_SMS_URL=https://rest.nexmo.com/sms/json
CALLBACK_SERVER_URL=https://your-public-url

For development, you can use http://localhost:8080 as the default callback URL. For production, provide a public URL (for example, via ngrok or a deployed server).

## 

Run the MCP server to expose the telephony tools to your LLM applications.

python telephony_server.py

## 

If you prefer running with Docker, you can build and start the container with Docker Compose. Use these commands to build, run, and view logs.

docker compose up --build

To run in the background:

docker compose up --build -d

To stop and remove containers:

docker compose down

View live logs:

docker compose logs -f

## Using with an MCP client

Connect your MCP client to the running Telephony MCP Server. The client can invoke `voice_call` to initiate a call or `send_sms` to deliver a text message. When the LLM determines a telephony action is needed, it calls the appropriate tool with the required parameters. The server handles the request via Vonage and returns the result to the LLM for inclusion in the conversation.

## Using with Claude Desktop or other MCP clients

Configure your MCP client to point to the Telephony MCP Server by updating the client’s MCP server connection settings and ensuring the server is reachable from the client environment.

## Key concepts and endpoints

The Telephony MCP Server integrates with LLM applications by offering tool definitions such as `voice_call` and `send_sms`. It also includes a Vonage Callback Server to listen for call events on a designated port and provides endpoints to view and manage event data.

## Callback server and Vonage events

The Vonage Callback Server listens on a public URL for event notifications (e.g., call started, completed, or failed). It stores events and exposes endpoints to check health and retrieve event history.

## Notes on configuration and security

Keep your Vonage credentials secure and do not expose them in client configurations. Use a separate, restricted Vonage application and monitor callbacks for correctness. For development, use a localhost callback URL and ngrok for public exposure only when necessary.

## Available tools

### voice\_call

Initiates a voice call to a specified number using Vonage and supports parameters like language and speaking style as needed by the LLM application.

### send\_sms

Sends an SMS message to a specified recipient using the Vonage SMS API.