TE
OfficialCommunication

Telnyx MCP Server for Voice, SMS, Real-Time

Build AI-powered voice assistants, send SMS campaigns, manage numbers, and integrate real-time messaging with the MCP server using streamable HTTP & SSE.

View on GitHub
Quick Install
npx -y @team-telnyx/telnyx-mcp-server

Overview

The Telnyx MCP Server is a reference implementation that implements the Model Context Protocol (MCP) to enable streaming, stateful interactions between AI models and telephony / messaging platforms. It provides a lightweight HTTP/SSE-based bridge so you can build applications that stream model outputs to voice calls, SMS channels, and real-time messaging endpoints without managing low-level connection plumbing.

Designed for developers, the server demonstrates how to integrate Telnyx voice, SMS, and real-time features with AI models (LLMs, ASR, TTS) using streamable HTTP requests and Server-Sent Events (SSE). Use it as a starting point to prototype AI voice assistants, handle two-way SMS conversations at scale, or attach real-time model responses to WebRTC and chat sessions.

Features

  • Implements MCP-style streaming over HTTP and SSE for model outputs
  • Examples for voice call integration (TTS/ASR) and sending/receiving SMS
  • Real-time messaging support for low-latency interactions
  • Number management and basic webhook handling examples
  • Local development workflow with environment-driven configuration
  • Reference client examples (JavaScript/Python) and curl snippets for testing

Installation / Configuration

Prerequisites:

  • Node.js (12+ or current LTS)
  • A Telnyx account and API credentials
  • Optional: an LLM provider API key (for text generation/TTS/ASR)

Clone and install:

git clone https://github.com/team-telnyx/telnyx-mcp-server.git
cd telnyx-mcp-server
npm install

Environment variables

Create a .env file (or set environment variables) used by the server. Typical entries:

# Telnyx API key for REST requests (manage numbers, SMS, voice)
TELNYX_API_KEY=sk_live_...

# API key used by MCP clients to authenticate to this server (shared secret)
MCP_SERVER_KEY=your_mcp_shared_secret

# Port and base URL for local development
PORT=3000
BASE_URL=http://localhost:3000

# Optional webhook secret used to verify Telnyx callbacks
WEBHOOK_SECRET=your_webhook_secret

Start the server:

# development
npm run dev

# production
npm start

By default the server listens on the configured PORT and exposes endpoints that implement MCP-style streaming and webhook handlers. Adjust BASE_URL when exposing your server through a tunnel (ngrok, Cloudflare Tunnel) for Telnyx callbacks and testing with public endpoints.

Available Resources

  • GitHub repository (reference implementation and examples): https://github.com/team-telnyx/telnyx-mcp-server
  • Telnyx developer documentation (voice, SMS, real-time) — consult for API-specific details and webhook setup
  • Example client snippets included in the repo (JavaScript & Python) showing how to connect to the server and consume streams
  • Local testing helpers: curl examples and Postman collection (if included in the repo) for quick verification

Quick Examples

Test SSE streaming (replace URL and API key as needed):

curl -N \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $MCP_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Hello, how can I help today?"}' \
  http://localhost:3000/mcp/sse

Test chunked (HTTP streaming) endpoint:

curl -N \
  -H "Authorization: Bearer $MCP_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Start a short conversation"}' \
  http://localhost:3000/mcp/stream

Client-side JavaScript (EventSource) example to receive SSE:

const es = new EventSource('http://localhost:3000/mcp/sse?token=YOUR_TOKEN');
es.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('chunk:', data);
};
es.onerror = (err) => console.error('SSE error', err);

Use Cases

  • AI-powered voice assistants

    • Attach a model to live voice calls. Stream model text-to-speech to callers and stream speech recognition back to the model so it can maintain conversational state and provide dynamic responses (hold music, IVR, or full conversational agents).

  • SMS campaigns and conversational messaging

    • Send campaign messages and handle replies programmatically. Use the MCP server to stream model-generated responses to inbound SMS and maintain session context across messages for natural multi-turn conversations.

  • Real-time chat and in-call features

    • Integrate low-latency model responses into chat widgets, WebRTC sessions, or multiplayer experiences. Real-time endpoints are useful for live assistance, moderation, or inserting AI-provided content into UX flows.

  • Number provisioning and management

    • Use the server as a control plane for automating Telnyx number provisioning, assigning webhooks, and routing inbound traffic into model-driven handlers.

Tips for Developers

  • Use a secure, short-lived shared secret (MCP_SERVER_KEY) to authenticate clients and webhooks during development.
  • Run the server behind a public tunnel (ngrok) when testing Telnyx callbacks or real phones.
  • Start with the provided examples (voice, SMS, real-time) and replace mock model calls with your preferred LLM / ASR / TTS providers as you prototype.

This MCP server is a practical skeleton for connecting streaming AI models to telephony and messaging systems—adapt the included examples to match your chosen model stack and Telnyx configuration.

Tags:communication