Telnyx MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Telnyx MCP Server send an SMS to +15551234567 saying 'Hello from MCP'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Telnyx Local Model Context Protocol (MCP) Server
⚠️ DEPRECATED: This Python-based MCP server is deprecated. Please migrate to the official TypeScript version:
New Repository: https://github.com/team-telnyx/telnyx-node/tree/master/packages/mcp-server
Official Telnyx Local Model Context Protocol (MCP) Server that enables interaction with powerful telephony, messaging, and AI assistant APIs. This server allows MCP clients like Claude Desktop, Cursor, Windsurf, OpenAI Agents and others to manage phone numbers, send messages, make calls, and create AI assistants.
Quickstart with Claude Desktop
Get your API key from the Telnyx Portal.
Install
uvx(Python package manager), install withcurl -LsSf https://astral.sh/uv/install.sh | sh,brew install uvor see theuvrepo for additional install methods.Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:
{
"mcpServers": {
"Telnyx": {
"command": "uvx",
"args": ["--from", "git+https://github.com/team-telnyx/telnyx-mcp-server.git", "telnyx-mcp-server"],
"env": {
"TELNYX_API_KEY": "<insert-your-api-key-here>"
}
}
}
}If you're using Windows, you will have to enable "Developer Mode" in Claude Desktop to use the MCP server. Click "Help" in the hamburger menu at the top left and select "Enable Developer Mode".
Related MCP server: VoIPbin MCP Server
Running After Download
Get your API key from the Telnyx Portal.
Install
uvx(Python package manager), install withcurl -LsSf https://astral.sh/uv/install.sh | sh,brew install uvor see theuvrepo for additional install methods.Clone the Git Repository
Use Git to download the Telnyx MCP Server locally:git clone https://github.com/team-telnyx/telnyx-mcp-server.git cd telnyx-mcp-serverConfigure and Run with uvx
In your Claude config, you can reference the local folder by using the--fromargument. For example:{ "mcpServers": { "Telnyx": { "command": "uvx", "args": ["--from", "/path/to/telnyx-mcp-server", "telnyx-mcp-server"], "env": { "TELNYX_API_KEY": "<insert-your-api-key-here>" } } } }This instructs Claude to run the server from the folder you cloned. Replace “/path/to/telnyx-mcp-server” with the actual location of the repository.
Available Tools
Assistant Tools
Create AI assistants with custom instructions and configurations
List existing assistants
Get assistant details
Update assistant properties
Delete assistants
Get assistant TEXML configurations
Call Control Tools
Make outbound phone calls
Hang up active calls
Transfer calls to new destinations
Play audio files during calls
Stop audio playback
Send DTMF tones
Speak text using text-to-speech
Messaging Tools
Send SMS and MMS messages
Get message details
Access and view ongoing SMS conversations (
resource://sms/conversations)
Phone Number Tools
List your phone numbers
Buy new phone numbers
Update phone number configurations
List available phone numbers
Connection Tools
List voice connections
Get connection details
Update connection configurations
Cloud Storage Tools
Create buckets compatible with Telnyx Cloud Storage
List buckets across all regions
Upload files
Download files
List objects in a bucket
Delete objects
Get bucket location information
Embeddings Tools
List existing embedded buckets
Scrape and embed a website URL
Create embeddings for your own files
Secrets Manager Tools
List integration secrets
Create new bearer or basic secrets
Delete integration secrets
Tool Filtering
You can selectively enable or disable specific tools when running the MCP server. This is useful when you only need a subset of the available functionality.
Listing Available Tools
To see all available tools:
uvx --from /path/to/telnyx-mcp-server telnyx-mcp-server --list-toolsEnabling Specific Tools
You can enable only specific tools using either:
Command-line argument:
uvx --from /path/to/telnyx-mcp-server telnyx-mcp-server --tools "send_message,get_message,list_phone_numbers"Environment variable:
{ "mcpServers": { "Telnyx": { "command": "uvx", "args": ["--from", "/path/to/telnyx-mcp-server", "telnyx-mcp-server"], "env": { "TELNYX_API_KEY": "<insert-your-api-key-here>", "TELNYX_MCP_TOOLS": "send_message,get_message,list_phone_numbers" } } } }
Excluding Specific Tools
You can exclude specific tools while enabling all others:
Command-line argument:
uvx --from /path/to/telnyx-mcp-server telnyx-mcp-server --exclude-tools "make_call,send_dtmf"Environment variable:
{ "mcpServers": { "Telnyx": { "command": "uvx", "args": ["--from", "/path/to/telnyx-mcp-server", "telnyx-mcp-server"], "env": { "TELNYX_API_KEY": "<insert-your-api-key-here>", "TELNYX_MCP_EXCLUDE_TOOLS": "make_call,send_dtmf" } } } }
Example Usage
Try asking Claude:
"Create an AI agent that can handle customer service for an e-commerce business"
"Send a text message to +5555551234 saying 'Your appointment is confirmed for tomorrow at 3pm'"
"Make a call to my customer at +5555551234 and transfer them to my support team"
"Find me a phone number in Chicago with area code 312"
"Create an auto-attendant system using Telnyx AI assistants and voice features"
Webhook Receiver
The MCP server includes a webhook receiver that can handle Telnyx webhooks directly through ngrok. This is useful for receiving call events and other notifications from Telnyx.
Enabling Webhooks
To enable the webhook receiver, you can either use the --webhook-enabled command-line flag or set the WEBHOOK_ENABLED=true environment variable. If an NGROK_AUTHTOKEN is also provided (see 'Ngrok Integration' below), the ngrok tunnel will be automatically attempted when the server starts. The command-line flag takes precedence if both are set.
Using Command-Line Flag:
telnyx-mcp-server --webhook-enabled --ngrok-enabledUsing Environment Variable:
Alternatively, set the WEBHOOK_ENABLED=true environment variable. This is often convenient when configuring via MCP client settings (see 'Webhook Configuration in Claude Desktop' below) or in .env files.
# Example for your shell
export WEBHOOK_ENABLED=true
export NGROK_AUTHTOKEN=your_ngrok_token # Also needed for ngrok
telnyx-mcp-serverNgrok Integration
To enable ngrok tunneling:
Get an ngrok authentication token from ngrok.com
Set the
NGROK_AUTHTOKENenvironment variable or use the--ngrok-authtokenflag:
# Using NGROK_AUTHTOKEN environment variable (recommended)
export NGROK_AUTHTOKEN=your_ngrok_token
telnyx-mcp-server --webhook-enabled # Or use WEBHOOK_ENABLED=true env var
# Or using --ngrok-authtoken command line flag
telnyx-mcp-server --webhook-enabled --ngrok-authtoken your_ngrok_tokenIf NGROK_AUTHTOKEN is set, the --ngrok-enabled flag is generally not required when webhooks are active.
When ngrok is enabled, the server will print the public URL that can be used to configure webhooks in the Telnyx Portal.
Important: If ngrok fails to initialize (e.g., due to an invalid authtoken, network issues, or conflicts with another ngrok process), the MCP server will exit on startup. Check the server logs for details (see Troubleshooting section).
Parent Process Monitoring
The MCP server monitors the parent process (Claude Desktop) and automatically exits when the parent process is gone. This ensures proper cleanup of resources even if Claude Desktop closes unexpectedly.
Webhook Monitoring and Runtime Control
You can inspect the current webhook and ngrok status by querying the
resource://webhook/inforesource.To retrieve a history of received webhook events, use the
get_webhook_eventstool.
Webhook Configuration in Claude Desktop
To enable webhooks in Claude Desktop, update your configuration:
{
"mcpServers": {
"Telnyx": {
"command": "uvx",
"args": ["--from", "git+https://github.com/team-telnyx/telnyx-mcp-server.git", "telnyx-mcp-server"],
"env": {
"TELNYX_API_KEY": "<insert-your-api-key-here>",
"NGROK_AUTHTOKEN": "<insert-your-ngrok-token-here>",
"WEBHOOK_ENABLED": "true", // Enables webhooks via environment variable
// Alternatively, you can use command-line flags in "args" instead of WEBHOOK_ENABLED in env:
// e.g., "args": ["--from", "git+https://github.com/team-telnyx/telnyx-mcp-server.git", "telnyx-mcp-server", "--webhook-enabled"],
}
}
}
}Webhook Example
Remote MCP Now Available
Telnyx now offers a remote MCP implementation based on the latest MCP specification. This allows you to access Telnyx's powerful communications APIs through a remotely hosted MCP server. No need to run the server locally. Learn more in the official documentation.
Contributing
If you want to contribute or run from source:
Clone the repository:
git clone https://github.com/team-telnyx/telnyx-mcp-server.git
cd telnyx-mcp-serverCreate a virtual environment and install dependencies using uv:
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]" # Includes development dependencies like ruffCreate a
.envfile and add your Telnyx API key:
echo "TELNYX_API_KEY=YOUR_API_KEY" > .envRun the tests to make sure everything is working:
pytestInstall the server in Claude Desktop:
mcp install src/telnyx_mcp_server/server.pyDebug and test locally with MCP Inspector:
mcp dev src/telnyx_mcp_server/server.py
Code Quality with Ruff
This project uses Ruff for linting and formatting Python code. Ruff is a fast Python linter and formatter written in Rust, designed to replace multiple Python code quality tools with a single, unified tool.
Installing Ruff
Ruff is included in the development dependencies. Install it with:
uv pip install -e ".[dev]"Using Ruff
Linting
To check your code for issues:
ruff check .To automatically fix issues where possible:
ruff check --fix .Formatting
To format your code:
ruff format .Pre-commit Workflow
For the best development experience, run these commands before committing changes:
# Format code
ruff format .
# Fix linting issues
ruff check --fix .
# Run tests
pytestConfiguration
Ruff is configured in the pyproject.toml file. The configuration includes:
Code style rules based on PEP 8
Import sorting
Docstring style checking (Google style)
Code complexity checks
And more
See the [tool.ruff] section in pyproject.toml for the complete configuration.
Troubleshooting
Logs when running with Claude Desktop can be found at:
Windows:
%APPDATA%\Claude\logs\mcp-server-telnyx.logmacOS:
~/Library/Logs/Claude/mcp-server-telnyx.log
MCP Telnyx: spawn uvx ENOENT
If you encounter the error "MCP Telnyx: spawn uvx ENOENT", confirm its absolute path by running this command in your terminal:
which uvxOnce you obtain the absolute path (e.g., /usr/local/bin/uvx), update your configuration to use that path (e.g., "command": "/usr/local/bin/uvx"). This ensures that the correct executable is referenced.
Server Fails to Start (Especially with Webhooks/Ngrok)
If the MCP server fails to start, particularly if you have webhooks enabled, it might be due to an issue with ngrok initialization. One common cause is an existing ngrok process running in the background, potentially from a previous server instance that didn't shut down cleanly.
Check for running processes: Use commands like
ps aux | grep telnyx-mcp-server(Linux/macOS) or check Task Manager (Windows) for any lingeringtelnyx-mcp-serverprocesses. Since ngrok is managed internally by the server, you typically won't see a separate 'ngrok' process.Kill old processes: If found, terminate these old processes.
Check logs: Review the server logs (locations mentioned above) for specific error messages related to ngrok or server startup.
Available Tools
46 toolscloud_storage_create_bucketC
Create a new bucket.
Args:
bucket_name: Required. Name of the bucket to create
region: Required. Region to create the bucket in (us-east-1, us-west-1, us-central-1)
Returns:
str: Success!! if it uploaded, otherwise returns an exception message
Inputs: request (required).
cloud_storage_delete_objectB
Delete an object from cloud storage.
Args: object_name: Required. Name of the object to delete bucket_name: Optional. Bucket to delete from (defaults to instance default) Returns: str: 'Success' if the object was deleted successfully
Inputs: request (required).
cloud_storage_download_fileA
Download a file from cloud storage.
Args: object_name: Required. Name of the object to download file_path: Required. Path where to save the downloaded file bucket_name: Optional. Bucket to download from (defaults to instance default) Returns: str: 'Success' if the file was downloaded successfully
Inputs: request (required).
cloud_storage_get_bucket_locationB
Get the region where a bucket is located.
Args: bucket_name: Optional. Name of the bucket. If None, uses default bucket.
Returns: str: The region where the bucket is located
Inputs: request (required).
cloud_storage_list_bucketsA
List all buckets across all regions.
Returns: List[Dict[str, str]]: List of dictionaries containing bucket information: - name: Name of the bucket - region: Region where the bucket is located
Inputs: no named parameters.
cloud_storage_list_objectsA
List objects in a bucket with optional prefix filtering.
Args: prefix: Optional. Only list objects beginning with this prefix. Defaults to "". bucket_name: Optional. Bucket to list from (defaults to instance default)
Returns: List[str]: List of object names
Inputs: request (required).
cloud_storage_upload_fileA
Upload a file to cloud storage.
Args:
absolute_file_path: Required. Absolute File Path to the file to upload
object_name: Optional. Name to give the object in storage (defaults to file name)
bucket_name: Optional. Bucket to upload to (defaults to instance default)
Returns:
str: Success!! if it uploaded, otherwise returns an exception message
Inputs: request (required).
create_assistantA
Create a new AI Assistant. The user will provide some details (sometimes detailed, sometimes vague) about the agent they want to create.
Args:
name: Required. Name of the assistant. If not provided, will be generated based on context.
model: Required. Model to use for the assistant. Defaults to meta-llama/Meta-Llama-3.1-70B-Instruct.
instructions: Required. Core instructions or behaviors for the agent.
description: Optional. A summary of the agent's purpose.
tools: Optional. List of tools for the assistant, each containing:
- type: Required. Type of tool ("function", "retrieval", "webhook",
"hangup", "send_dtmf", "transfer").
- function: Optional. For function tools, contains:
- name: Required. Name of the function.
- description: Optional. Description of the function.
- parameters: Required. Parameters schema for the function.
- retrieval: Optional. For retrieval tools, contains:
- bucket_ids: Required. List of bucket IDs for retrieval.
- max_num_results: Optional. Maximum number of results to retrieve.
- webhook: Optional. For webhook tools, contains:
- name: Required. The name of the tool.
- description: Required. The description of the tool.
- url: Required. The URL of the external tool to be called. This URL can be
templated like: https://example.com/api/v1/{id}, where {id} is a
placeholder for a value that will be provided by the assistant if
path_parameters are provided with the id attribute.
- method: Optional. The HTTP method to be used. Possible values:
[GET, POST, PUT, DELETE, PATCH]. Default value: POST.
- headers: Optional. Array of header objects with:
- name: String name of the header.
- value: String value of the header. Supports mustache templating.
e.g., Bearer {{#integration_secret}}test-secret{{/integration_secret}}.
Secrets can be found in list_integration_secrets
- body_parameters: Optional. JSON Schema object describing the body parameters:
- properties: Object defining the properties of the body parameters.
- required: Array of strings listing required properties.
- type: String. Possible value: "object".
- path_parameters: Optional. JSON Schema object describing the path parameters:
- properties: Object defining the properties of the path parameters.
- required: Array of strings listing required properties.
- type: String. Possible value: "object".
- query_parameters: Optional. JSON Schema object describing the query parameters:
- properties: Object defining the properties of the query parameters.
- required: Array of strings listing required properties.
- type: String. Possible value: "object".
- hangup: Optional. For hangup tools, contains:
- description: Optional. Description of the hangup function. Defaults to
"This tool is used to hang up the call."
- send_dtmf: Optional. For DTMF tools, contains an empty object. This tool
allows sending DTMF tones during a call.
- transfer: Optional. For transfer tools, contains:
- targets: Required. Array of transfer targets, each with:
- name: Optional. Name of the target.
- to: Required. Destination number or SIP URI.
- from: Required. Number or SIP URI placing the call.
- custom_headers: Optional. Array of custom SIP headers, each with:
- name: Required. Name of the header.
- value: Required. Value of the header. Supports mustache templating.
greeting: Optional. A short welcoming message. Will be generated if not provided.
llm_api_key_ref: Optional. LLM API key reference.
transcription: Optional. Transcription settings with:
- model: Optional. Model to use for transcription.
messaging_settings: Optional. Messaging settings with:
- default_messaging_profile_id: Optional. Default messaging profile ID.
- delivery_status_webhook_url: Optional. Webhook URL for delivery status updates.
insight_settings: Optional. Insight settings with:
- insight_group_id: Optional. Insight group ID.
dynamic_variables_webhook_url: Optional. Dynamic variables webhook URL.
dynamic_variables: Optional. Dynamic variables dictionary.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
create_call_control_applicationA
Create a call control application.
Args: application_name: Required. A user-assigned name to help manage the application. webhook_event_url: Required. The URL where webhooks related to this connection will be sent. Must include a scheme, such as 'https'. active: Optional boolean. Specifies whether the connection can be used. Defaults to True. anchorsite_override: Optional. Directs Telnyx to route media through the site with the lowest round-trip time. Defaults to "Latency". dtmf_type: Optional. Sets the type of DTMF digits sent from Telnyx to this Connection. Defaults to "RFC 2833". first_command_timeout: Optional boolean. Specifies whether calls should hangup after timing out. first_command_timeout_secs: Optional integer. Seconds to wait before timing out a dial command. Defaults to 30. inbound: Optional dictionary. Inbound call settings with these possible keys: - channel_limit: Optional integer. Maximum number of concurrent inbound calls. - shaken_stir_enabled: Optional boolean. Enable SHAKEN/STIR verification for inbound calls. - sip_subdomain: Optional string. SIP subdomain for the application. - sip_subdomain_receive_settings: Optional string. Settings for SIP subdomain receiving. outbound: Optional dictionary. Outbound call settings with these possible keys: - channel_limit: Optional integer. Maximum number of concurrent outbound calls. - outbound_voice_profile_id: Optional string. ID of the outbound voice profile to use. webhook_api_version: Optional. Determines which webhook format will be used. Defaults to "1". webhook_event_failover_url: Optional. The failover URL for webhooks if the primary URL fails. webhook_timeout_secs: Optional integer. Seconds to wait before timing out a webhook. Returns: Dict[str, Any]: Response data
Inputs: request (required).
create_embeddingsC
Embed a bucket that containe files.
Args: bucket_name: Required. Bucket Name. The bucket must exist (string) document_chunk_size: Optional. Document Chunk Size (integer) document_chunk_overlap_size: Optional. Document Chunk Overlap Size (integer) embedding_model: Optional. Supported models (thenlper/gte-large, intfloat/multilingual-e5-large, sentence-transformers/all-mpnet-base-v2) to vectorize and embed documents. loader: Optional. (default, intercom) (string)
Agent should prefer only rely on required fields unless user explicitly provides values for optional fields.
Returns: Dict[str, Any]: Response data containing the embeddings
Inputs: request (required).
create_integration_secretA
Create an integration secret.
Args: identifier: Required. The unique identifier of the secret. type: Required. The type of secret (bearer, basic). token: Optional. The token for the secret (required for bearer type). username: Optional. The username for the secret (required for basic type). password: Optional. The password for the secret (required for basic type).
Returns: Dict[str, Any]: Response data containing the created Integration Secret Object (record_type: "integration_secret")
Inputs: request (required).
create_messaging_profileA
Create a messaging profile.
Args: name: Required. A user friendly name for the messaging profile. whitelisted_destinations: Required. List of destinations to which messages are allowed to be sent (ISO 3166-1 alpha-2 country codes). Use ["*"] to allow all destinations. enabled: Optional boolean. Specifies whether the messaging profile is enabled. Defaults to True. webhook_url: Optional. The URL where webhooks related to this messaging profile will be sent. webhook_failover_url: Optional. The failover URL for webhooks if the primary URL fails. webhook_api_version: Optional. Webhook format version ("1", "2", or "2010-04-01"). Defaults to "2". number_pool_settings: Optional dictionary. Number pool configuration with possible settings: - use_pool: Boolean indicating whether to use number pool. - sticky_sender: Boolean indicating whether to use sticky sender. - pool_weights: Dictionary mapping phone number types to weights. url_shortener_settings: Optional dictionary. URL shortener configuration with possible settings: - enabled: Boolean indicating whether URL shortening is enabled. - domains: List of domains to be shortened. alpha_sender: Optional. The alphanumeric sender ID for destinations requiring it. daily_spend_limit: Optional. Maximum daily spend in USD before midnight UTC. daily_spend_limit_enabled: Optional boolean. Whether to enforce the daily spend limit. mms_fall_back_to_sms: Optional boolean. Enables SMS fallback for MMS messages. mms_transcoding: Optional boolean. Enables automated resizing of MMS media.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
delete_integration_secretB
Delete an integration secret.
Args: id: Required. Secret ID.
Returns: Dict[str, Any]: Empty response on success
Inputs: id (required).
embed_urlC
Scrape and embed a given URL. For a given website, this tool will scrape the content of the pages and save the content in a new bucket. That bucket will be automatically embedded.
Args: url: Required. URL to be scraped and embedded.
Returns: Dict[str, Any]: Response data containing bucket information
Inputs: request (required).
get_assistantB
Get an AI Assistant by ID.
Args: assistant_id: Required. Assistant ID. fetch_dynamic_variables_from_webhook: Optional boolean. Whether to fetch dynamic variables from webhook. from_: Optional. From parameter for dynamic variables. to: Optional. To parameter for dynamic variables. call_control_id: Optional. Call control ID for dynamic variables.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
get_assistant_texmlA
Get an assistant's TEXML by ID.
Args: assistant_id: Assistant ID
Returns: str: Assistant TEXML content
Inputs: assistant_id (required).
get_call_control_applicationC
Retrieve a specific call control application.
Args: id: Required. Identifies the call control application.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
get_connectionA
Get a connection by ID.
Args: id: Required. Connection ID.
Returns: Dict[str, Any]: Response data
Inputs: id (required).
get_messageA
Retrieve a message by ID.
Args: message_id: The ID of the message to retrieve
Returns: Dict[str, Any]: Response data containing message details
Inputs: message_id (required).
get_messaging_profileB
Retrieve a messaging profile by ID.
Args: profile_id: The ID of the messaging profile to retrieve
Returns: Dict[str, Any]: Response data containing messaging profile details
Inputs: profile_id (required).
get_phone_numberA
Get a phone number by ID.
Args: id: Phone number ID as string
Returns: Dict[str, Any]: Response data containing Number Object(s) (record_type: "phone_number")
Inputs: id (required).
get_webhook_eventsA
Get the most recent webhook events received by the handler.
Args: limit: Maximum number of events to return (default: 10) event_type: Filter events by type (default: all types)
Returns: Dict containing webhook events and metadata
Inputs: limit, event_type.
hangupB
Hang up a call.
Args: call_control_id: Required. Call control ID.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
initiate_phone_number_orderC
Initiate a phone number order.
Args: phone_number: Required. Phone number to buy. connection_id: Optional. Connection ID to associate with the number.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
list_assistantsB
List all AI Assistants.
Returns: Dict[str, Any]: List of assistants
Inputs: no named parameters.
list_available_phone_numbersB
List available phone numbers.
Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 20. filter_phone_number_starts_with: Optional. Filter numbers starting with pattern. filter_phone_number_ends_with: Optional. Filter numbers ending with pattern. filter_phone_number_contains: Optional. Filter numbers containing pattern. filter_locality: Optional. Filter by locality (city). filter_administrative_area: Optional. Filter by administrative area (state). filter_country_code: Optional. Filter by country code. filter_features: Optional. List of features to filter by.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
list_call_control_applicationsA
List call control applications.
Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 20. filter_application_name_contains: Optional. Filter by application name (case-insensitive, min 3 characters). filter_outbound_voice_profile_id: Optional. Filter by associated outbound voice profile ID. sort: Optional. Sort order for results (created_at, connection_name, active). Defaults to created_at.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
list_connectionsB
List connections.
Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 20. filter_connection_name_contains: Optional. Filter by connection name. filter_outbound_voice_profile_id: Optional. Filter by outbound voice profile ID. sort: Optional. Sort order (created_at, connection_name, active).
Returns: Dict[str, Any]: Response data
Inputs: request (required).
list_embedded_bucketsA
List user embedded buckets.
Returns: Dict[str, Any]: Response data eg: { "data": { "buckets": [ "string" ] } }
Inputs: no named parameters.
list_integration_secretsA
List integration secrets.
Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 25. filter_type: Optional. Filter by secret type (bearer, basic).
Returns: Dict[str, Any]: Response data containing Integration Secret Object(s) (record_type: "integration_secret")
Inputs: request (required).
list_messaging_profilesB
List messaging profiles.
Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 20. filter_name: Optional. Filter by profile name.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
list_phone_numbersC
List phone numbers.
Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 20. filter_tag: Optional. Filter by phone number tag. filter_phone_number: Optional. Filter by phone number. filter_status: Optional. Filter by phone number status. filter_country_iso_alpha2: Optional. Filter by country ISO alpha-2 code.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
make_callC
Make a call.
Args: to: Required. Destination number or SIP URI. from_: Required. Source number. connection_id: Optional. Connection ID of a call control application to use for the call (same as call_control_application_id).
Returns: Dict[str, Any]: Response data
Inputs: request (required).
mcp_telnyx_delete_assistantB
Delete an AI Assistant.
Args: id: Assistant ID as string
Returns: Dict[str, Any]: Response data containing deletion status
Inputs: id (required).
playback_startA
Start audio playback on a call.
Args: call_control_id: Required. Call control ID. audio_url: Required. URL of audio file to play. loop: Optional. Number of times to loop the audio. Valid values: infinity, 1, 2, 3, 4, 5. overlay: Optional boolean. Whether to overlay the audio on existing audio. Defaults to False. stop: Optional. Which audio to stop. Valid values: current, all. target_legs: Optional. Which leg(s) to play the audio on. Valid values: self, peer, both.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
playback_stopA
Stop audio playback on a call.
Args: call_control_id: Required. Call control ID. overlay: Optional boolean. Whether to stop overlay audio. Defaults to False. stop: Optional. Which audio to stop. Valid values: current, all.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
send_dtmfA
Send DTMF tones on a call.
Args: call_control_id: Required. Call control ID. digits: Required. DTMF digits to send (0-9, *, #, w, W). duration_millis: Optional integer. Duration of each digit in milliseconds. Defaults to 500.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
send_messageC
Send a message.
Args: from_: Required. Sending address (phone number, alphanumeric sender ID, or short code). to: Required. Receiving address(es). text: Required. Message text. messaging_profile_id: Optional. Messaging profile ID. subject: Optional. Message subject. media_urls: Optional. List of media URLs. webhook_url: Optional. Webhook URL. webhook_failover_url: Optional. Webhook failover URL. use_profile_webhooks: Optional boolean. Whether to use profile webhooks. Defaults to True. type: Optional. The protocol for sending the message, either "SMS" or "MMS". auto_detect: Optional boolean. Automatically detect if an SMS message is unusually long.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
speakA
Speak text on a call using text-to-speech.
Args: call_control_id: Required. Call control ID. payload: Required. Text to speak. voice: Required. Voice to use. Defaults to female payload_type: Optional. Type of payload. Valid values: text, ssml. Defaults to "text". service_level: Optional. Service level for TTS. Valid values: basic, premium. Defaults to "basic". stop: Optional. Which audio to stop. Valid values: current, all. language: Optional. Language code (e.g., 'en-US', 'arb').
Returns: Dict[str, Any]: Response data
Inputs: request (required).
start_assistant_callA
Start a call using an AI Assistant with a phone number.
Args: assistant_id: Required. ID of the assistant to use for the call. to: Required. Destination phone number to call. from_: Required. Source phone number to call from (must be a number on your Telnyx account).
Returns: Dict[str, Any]: Response data from the call initiation
Inputs: to (required), from_ (required), assistant_id (required).
transferC
Transfer a call to a new destination.
Args: call_control_id: Required. Call control ID. to: Required. Destination number or SIP URI. from_: Required. Source number.
Returns: Dict[str, Any]: Response data
Inputs: request (required).
update_assistantA
Update an AI Assistant. Once there is an agent created, you can talk the user about what can be updated in an easy manner, rather than asking for a long list of fields to update.
Args:
assistant_id: Required. ID of the assistant to update.
name: Optional. Name of the assistant.
model: Optional. Model to use for the assistant.
instructions: Optional. Core instructions or behaviors for the agent.
description: Optional. A summary of the agent's purpose.
tools: Optional. List of tools for the assistant, each containing:
- type: Required. Type of tool (ANY of "hangup", "retrieval", "send_dtmf",
"transfer", "webhook").
- retrieval: Optional. For retrieval tools, contains:
- bucket_ids: Required. List of bucket IDs for retrieval.
- max_num_results: Optional. Maximum number of results to retrieve.
- webhook: Optional. For webhook tools, contains:
- name: Required. The name of the tool.
- description: Required. The description of the tool.
- url: Required. The URL of the external tool to be called. This URL can be
templated like: https://example.com/api/v1/{id}, where {id} is a
placeholder for a value that will be provided by the assistant if
path_parameters are provided with the id attribute.
- method: Optional. The HTTP method to be used. Possible values:
[GET, POST, PUT, DELETE, PATCH]. Default value: POST.
- headers: Optional. Array of header objects with:
- name: String name of the header.
- value: String value of the header. Supports mustache templating,
e.g., Bearer {{#integration_secret}}test-secret{{/integration_secret}}.
Secrets can be found in list_integration_secrets
- body_parameters: Optional. JSON Schema object describing the body parameters:
- properties: Object defining the properties of the body parameters.
- required: Array of strings listing required properties.
- type: String. Possible value: "object".
- path_parameters: Optional. JSON Schema object describing the path parameters:
- properties: Object defining the properties of the path parameters.
- required: Array of strings listing required properties.
- type: String. Possible value: "object".
- query_parameters: Optional. JSON Schema object describing the query parameters:
- properties: Object defining the properties of the query parameters.
- required: Array of strings listing required properties.
- type: String. Possible value: "object".
- hangup: Optional. For hangup tools, contains:
- description: Optional. Description of the hangup function.
- send_dtmf: Optional. For DTMF tools, contains an empty object. This tool
allows sending DTMF tones during a call.
- transfer: Optional. For transfer tools, contains:
- targets: Required. Array of transfer targets, each with:
- name: Optional. Name of the target.
- to: Required. Destination number or SIP URI.
- from: Required. Number or SIP URI placing the call.
- custom_headers: Optional. Array of custom SIP headers, each with:
- name: Required. Name of the header.
- value: Required. Value of the header. Supports mustache templating.
eg: {{#integration_secret}}test-secret{{/integration_secret}}
to be used with integration secrets (Available secrets can be
found in list_integration_secrets)
greeting: Optional. A short welcoming message used by the agent.
llm_api_key_ref: Optional. LLM API key reference. This is meant to be used
for models provided by external vendors. eg: openai, anthropic, Groq, xai-org.
Available secrets can be found in list_integration_secrets
transcription: Optional. Transcription settings with:
- model: Optional. Model to use for transcription.
telephony_settings: Optional. Telephony settings with:
- default_texml_app_id: Optional. Default TeXML application ID.
messaging_settings: Optional. Messaging settings with:
- default_messaging_profile_id: Optional. Default messaging profile ID.
- delivery_status_webhook_url: Optional. Webhook URL for delivery status updates.
insight_settings: Optional. Insight settings with:
- insight_group_id: Optional. Insight group ID.
dynamic_variables_webhook_url: Optional. Dynamic variables webhook URL.
dynamic_variables: Optional. Dynamic variables dictionary.
Returns: Dict[str, Any]: Response data
Inputs: request (required), assistant_id (required).
update_connectionA
Update a connection.
Note: The Telnyx API does not support updating connections directly. Only GET, HEAD, and OPTIONS methods are allowed. Please create a new connection with the desired settings instead.
Args: id: Required. Connection ID. data: Required. Update data.
Returns: Dict[str, Any]: Response data
Raises: Exception: The Telnyx API does not support updating connections directly.
Inputs: id (required), data (required).
update_messaging_profileA
Update a messaging profile.
Args: profile_id: Required. The ID of the messaging profile to update. name: Optional. A user friendly name for the messaging profile. enabled: Optional boolean. Specifies whether the messaging profile is enabled. webhook_url: Optional. The URL where webhooks related to this messaging profile will be sent. webhook_failover_url: Optional. The failover URL for webhooks if the primary URL fails. webhook_api_version: Optional. Webhook format version ("1", "2", or "2010-04-01"). whitelisted_destinations: Optional list. Destinations to which messages are allowed (ISO 3166-1 alpha-2 country codes). Use ["*"] to allow all destinations. v1_secret: Optional. Secret used to authenticate with v1 endpoints. number_pool_settings: Optional dictionary. Number pool configuration with possible settings: - use_pool: Boolean indicating whether to use number pool. - sticky_sender: Boolean indicating whether to use sticky sender. - pool_weights: Dictionary mapping phone number types to weights. url_shortener_settings: Optional dictionary. URL shortener configuration with possible settings: - enabled: Boolean indicating whether URL shortening is enabled. - domains: List of domains to be shortened. alpha_sender: Optional. The alphanumeric sender ID for destinations requiring it. daily_spend_limit: Optional. Maximum daily spend in USD before midnight UTC. daily_spend_limit_enabled: Optional boolean. Whether to enforce the daily spend limit. mms_fall_back_to_sms: Optional boolean. Enables SMS fallback for MMS messages. mms_transcoding: Optional boolean. Enables automated resizing of MMS media.
Returns: Dict[str, Any]: Response data
Inputs: request (required), profile_id (required).
update_phone_numberC
Update a phone number.
Args: id: Required. Phone number ID. connection_id: Optional. Connection ID to associate with the number. tags: Optional. List of tags to associate with the number.
Returns: Dict[str, Any]: Response data
Inputs: id (required), request (required).
update_phone_number_messaging_settingsC
Update the messaging profile and/or messaging product of a phone number.
Args: id: Required. The phone number ID to update. messaging_profile_id: Optional. Configure the messaging profile this phone number is assigned to. Set to null to keep the current value, set to empty string to unassign, or set to a UUID to assign to that messaging profile. messaging_product: Optional. Configure the messaging product for this number. Set to null to keep the current value, or set to a product ID to change.
Returns: Dict[str, Any]: Response data
Inputs: id (required), request (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 46 tools
Several tools have overlapping purposes: `list_embedded_buckets` vs `cloud_storage_list_buckets`, `create_embeddings` vs `embed_url`, and `update_phone_number` vs `update_phone_number_messaging_settings` all could confuse an agent. The `update_connection` tool is a non-functional trap that always throws an exception, making it worse than useless.
Naming conventions are inconsistent across domains: some tools use `cloud_storage_*` prefix, others use plain `verb_noun`, and `mcp_telnyx_delete_assistant` is an outlier with an unusual prefix. There is no uniform pattern, though most names are readable.
With 46 tools, this server is overstuffed. It spans cloud storage, AI assistants, call control, messaging, phone numbers, and integration secrets—far too many distinct domains for a single MCP server. It would be better split into focused servers.
CRUD coverage is uneven: messaging profiles lack delete, connections lack create/delete, call control applications lack update/delete, and cloud storage lacks delete bucket. The non-functional `update_connection` tool creates a false sense of capability, and there are no update tools for integration secrets.
Related MCP Connectors
The Telnyx MCP server is an official implementation of the Model Context Protocol that enables AI clients (like Claude Desktop, Cursor, and OpenAI Agents) to interact with Telnyx's telephony, messaging, and AI assistant APIs. It provides comprehensive capabilities including making and managing phone calls, sending SMS/MMS messages, purchasing and configuring phone numbers, creating AI assistants with custom instructions, managing cloud storage buckets, scraping and embedding website content, and handling integration secrets. The server exists as both a local implementation and a remotely hosted version, allowing developers to integrate real-world communication infrastructure directly into AI applications.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server for the seven.io API, enabling SMS, voice, RCS messaging, and account management through natural language.4418 npm1MIT

VoIPbin MCP Serverofficial
AlicenseBqualityBmaintenanceAn MCP server that enables AI assistants to interact with the VoIPbin CPaaS platform, exposing tools for managing calls, flows, messaging, conferencing, and more.661MIT- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for TELNYX integration, enabling AI assistants to send SMS messages, make voice calls, and handle incoming communications via webhooks.MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server enabling AI assistants to make voice calls, send SMS/MMS, and manage group conversations using Twilio and OpenAI.21 npmMIT