telnyx-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TELNYX_API_KEY | Yes | Telnyx API key (Portal → Auth → API Keys). Required; without it the server exits immediately with exit code 78. | |
| TELNYX_TTS_OUTPUT_DIR | No | Where MP3 files are written. Must be an existing absolute path. Defaults to <os-temp>/telnyx-mcp. | |
| TELNYX_TTS_TIMEOUT_MS | No | HTTP timeout per attempt. | 120000 |
| TELNYX_TTS_EMBED_AUDIO | No | speak and render_script also return the MP3 as an MCP audio block (up to 8 MB) when true; false (also 0/no/off) returns the JSON only. | true |
| TELNYX_TTS_MAX_RETRIES | No | Attempts per request (429/5xx/network, with backoff). | 3 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Telnyx text-to-speech. Use list_voices to find a voice id, estimate_cost before long jobs, speak for a single text and render_script for markdown with [PAUSE n] markers. Audio is written to disk and referenced by absolute path — it is never returned inline.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_voicesA | Lists available Telnyx text-to-speech voices. The full catalogue has thousands of entries, so results are filtered and paged: pass language ("de"), provider ("telnyx") or a search term. Returns "returned of matched of total" plus a per-provider breakdown. |
| speakA | Synthesises text with a Telnyx voice and writes an MP3 file. Returns the absolute file path, byte size, measured duration, character count and the estimated list-price cost, plus the MP3 itself as an audio block (up to 8 MB, unless TELNYX_TTS_EMBED_AUDIO=false). |
| render_scriptA | Renders a markdown script into a single continuous MP3. Lines consisting only of "[PAUSE n]" become n seconds of real silence; text is split at sentence boundaries and synthesised segment by segment, then joined on MP3 frame level without re-encoding. Returns the file path, the measured total duration and the duration of every segment, plus the MP3 as an audio block (up to 8 MB, unless TELNYX_TTS_EMBED_AUDIO=false). |
| estimate_costA | Estimates the list-price cost for a character count, a text or a full [PAUSE n] script — without calling the Telnyx API. Use this before rendering long scripts. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 4 tools
Each tool maps to a distinct step in the TTS workflow: discovering voices, synthesising single text, rendering multi-segment scripts, and estimating cost without an API call. The only mild overlap is between speak and render_script, both producing MP3s, but the descriptions make the plain-text vs markdown-script-with-pauses boundary clear.
All names use snake_case and are mostly verb_noun (list_voices, render_script, estimate_cost). The bare verb speak is a minor deviation but still readable and unambiguous in this context.
Four tools is compact and each earns its place in the voice-synthesis flow. Slightly thin — a voice-detail or provider-listing tool could round it out — but nothing feels redundant.
The surface covers the core lifecycle: discover voices, preview cost, synthesise text, and render full scripts with silence insertion. Minor gaps exist (no voice metadata lookup, no output format/quality options beyond MP3, no batch/list of generated files), but agents can work around them.