Telnyx TypeScript API Library

The Telnyx MCP server implements a "Code Mode" scheme designed for deterministic and repeatable complex tasks. Instead of just calling APIs, the agent interacts with two specific tools:

1. Docs Search Tool: Allows the agent to query documentation about the Telnyx API/SDK.
2. Code Tool: Allows the agent to write code against the TypeScript SDK. This code is executed in an isolated sandbox environment (without web or filesystem access). The results or printed output from the code are returned to the agent.

This allows an agent to write, test, and verify logic using the actual SDK before finalizing a task.

List methods in the Telnyx API are paginated. You can use the for await ... of syntax to automatically iterate through all items across all pages.

Alternatively, you can manually paginate using page.hasNextPage() and page.getNextPage().

// Auto-pagination with for await
for await (const item of client.accessIPAddress.list({ 'page[size]': 50 })) {
  console.log(item);
}

// Manual pagination
let page = await client.accessIPAddress.list({ 'page[number]': 1, 'page[size]': 50 });
while (page.hasNextPage()) {
  page = await page.getNextPage();
}

The Telnyx TypeScript SDK requires TypeScript >= 4.9.

Supported Runtimes:

• Node.js: 20 LTS or later (non-EOL).
• Bun: 1.0 or later.
• Deno: v1.28.0 or higher.
• Web Browsers: Up-to-date Chrome, Firefox, Safari, Edge, etc.
• Edge/Serverless: Cloudflare Workers, Vercel Edge Runtime, Nitro v2.6 or greater.
• Testing: Jest 28 or greater (with "node" environment; "jsdom" is not supported).

Note: React Native is currently not supported.

Parameters expecting files can accept several formats: a Node.js fs.ReadStream, a web File instance, a fetch Response, or the toFile helper provided by the library. Using fs.createReadStream() is recommended for Node.js environments.

import fs from 'fs';
import Telnyx, { toFile } from 'telnyx';

const client = new Telnyx();

// Using fs.createReadStream
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: fs.createReadStream('/path/to/file'),
});

// Using the toFile helper
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: await toFile(Buffer.from('my bytes'), 'file'),
});

The telnyx-mcp package is a Model Context Protocol (MCP) server that allows AI agents to interact with the Telnyx API. It supersedes the legacy Python-based MCP server and provides cross-platform support, including native Windows support via Node.js.

Direct Invocation

You can run the server directly using npx. Ensure you have the required environment variables set:

export TELNYX_API_KEY="My API Key"
export TELNYX_PUBLIC_KEY="My Public Key"
export TELNYX_CLIENT_ID="My Client ID"
export TELNYX_CLIENT_SECRET="My Client Secret"
npx -y telnyx-mcp@latest

Windows Setup

For native Windows users, use PowerShell and Node.js 20 LTS or later:

$env:TELNYX_API_KEY = "My API Key"
npx -y telnyx-mcp@latest

To run the Messaging example, you must first install the dependencies and then execute the main script using ts-node. Ensure you have your Telnyx API Key configured in your environment before running the command.

# 1. Install dependencies
npm install

# 2. Set your API Key
export TELNYX_API_KEY=YOUR_TELNYX_API_KEY

# 3. Run the example
npm run start

You can launch the server as a remote service using Streamable HTTP transport by using the --transport=http flag.

Configuration

When connecting a client to a remote instance (e.g., hosted at http://localhost:3000), use the following configuration structure:

{
  "mcpServers": {
    "telnyx_api": {
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer <auth value>"
      }
    }
  }
}

Authorization

Authorization can be provided via:

• The Authorization header using the Bearer scheme.
• The x-telnyx-api-key header (equivalent to the apiKey client option, using bearerAuth).

To run the webhook verification demonstration locally, follow these steps:

1. Install dependencies:

   npm install

2. Configure environment variables: You must export your Telnyx API Key and your Webhook Signing Public Key:

   export TELNYX_API_KEY=your_api_key
   export TELNYX_PUBLIC_KEY=your_base64_public_key

3. Run the script:

   npm start

To run the AI SDK example, install the dependencies and execute the start script defined in package.json. You must provide your Telnyx API Key via the TELNYX_API_KEY environment variable.

export TELNYX_API_KEY=YOUR_TELNYX_API_KEY
npm install
npm run start

To run the Numbers SDK example, you must first install the dependencies and then execute the main script using ts-node. Ensure you have your Telnyx API Key configured in your environment variables before running the command.

# 1. Install dependencies
npm install

# 2. Set your API Key
export TELNYX_API_KEY=YOUR_TELNYX_API_KEY

# 3. Run the example
npm run start

The public key is required to verify signatures locally. To get it:

1. Log into Telnyx Mission Control.
2. Navigate to Settings → Public Keys.
3. Copy your Webhook Signing Public Key (it will be in base64 format).
4. Export it to your environment as TELNYX_PUBLIC_KEY.