W3J Telnyx MCP

MCP server exposing the full Telnyx API as Model Context Protocol tools, plus an autonomous voice agent builder that deploys live AI receptionists from a YAML spec.

Quick start

# Install
git clone https://github.com/mnjbold/w3j-telnyx-mcp.git
cd w3j-telnyx-mcp
uv venv .venv --python 3.12 --seed
source .venv/bin/activate  # Linux/macOS
# or: .venv\Scripts\Activate.ps1  (Windows)

uv sync --all-extras

# Health check
python -m telnyx_mcp.utils.env
python -m telnyx_mcp.clients.telnyx_client

# Start MCP server (stdio — for Claude Desktop / Cursor / Windsurf)
python -m telnyx_mcp.server

# Start MCP server (HTTP — for remote MCP clients)
python -m telnyx_mcp.server --transport http --host 0.0.0.0 --port 8765

# Deploy an agent from YAML
python agent_builder/builder.py agents/my-agent/spec.yaml --dry-run
python agent_builder/builder.py agents/my-agent/spec.yaml

What you get

Tool surface	Tools
numbers	search, order, list, get, update
voice	dial, transfer, hangup, answer, reject, start/stop AI assistant, recordings
assistants	CRUD AI Assistants
infrastructure	Call Control Apps, Outbound Voice Profiles, Messaging Profiles, Voice Clones
messaging	send SMS
utility	balance, account summary, health check

Deploy a voice agent

# From YAML spec
python agent_builder/builder.py agents/w3j-llc-concierge/spec.yaml

# agents/my-agent/spec.yaml
name: My Agent
instructions: |
  You are a friendly receptionist for Acme Corp...
country_code: US
area_code: "415"
buy_number: true
webhook_url: https://your-server/webhooks/telnyx
model: openai/gpt-4o
voice: Telnyx.KokoroTTS.af_heart

CI/CD

Push to main → GitHub Actions CI runs pytest + type check + lint. See .github/workflows/ci.yml.

License

MIT