| name | voice |
| description | Voice agent scaffolding — Telnyx AI Assistant + Call Control via MCP, Cloudflare Worker webhook, phone number provisioning directly from Claude |
| allowed-tools | ["Read","Write","AskUserQuestion","mcp__claude_ai_Telnyx__invoke_api_endpoint","mcp__claude_ai_Telnyx__list_api_endpoints","mcp__claude_ai_Telnyx__get_api_endpoint_schema"] |
Voice — Telnyx AI Assistant Scaffolding
Scaffold a Telnyx AI Assistant that lets you manage your CKS project by phone. Provisions via Telnyx MCP — no external bridge required.
Architecture
Inbound call to Telnyx number
↓
Call Control Application
↓ webhook: call.initiated → call_control_id
Cloudflare Worker (~15 lines)
↓ POST /v2/calls/{call_control_id}/actions/ai_assistant/start
Telnyx AI Assistant
— system prompt: CKS concierge instructions
— model: Claude (via Telnyx LLM gateway)
— handles STT + conversation + TTS natively
What the cks:voice-setup Agent Provisions via MCP
- AI Assistant —
create_ai_assistants with CKS concierge system prompt
- Call Control Application —
create_call_control_applications with Cloudflare Worker URL as webhook
- Phone number selection —
list_available_phone_numbers filtered by country/region
- Cloudflare Worker — scaffolded locally, deployed by user
AI Assistant System Prompt (write to .voice/system-prompt.txt)
You are a voice assistant managing a software project built with CKS (Claude Code Starter Kit).
Rules:
- Never use markdown, bullets, headers, or numbered lists
- Maximum 2 sentences per response
- Use spoken language: say "the sprint phase" not "Phase 3"
- Confirm verbally before any destructive action
- Say "one moment please" when processing
- If unsure, ask one clarifying question
You understand these project management commands:
- "What's the status?" → summarize current phase and open tasks
- "Proceed with [phase]" → confirm and advance to next phase
- "What's left to ship?" → list open acceptance criteria
- "Start planning [feature]" → begin discovery for that feature
- "Any issues?" → report blocking problems
Keep responses conversational and brief. You are managing a real software project.
Cloudflare Worker Scaffold (.voice/worker.js)
Deploys to Cloudflare Workers. Receives Telnyx call webhook and starts AI assistant.
export default {
async fetch(request, env) {
const body = await request.json();
const event = body?.data?.event_type;
const callControlId = body?.data?.payload?.call_control_id;
if (event === 'call.initiated' && callControlId) {
await fetch(`https://api.telnyx.com/v2/calls/${callControlId}/actions/ai_assistant/start`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${env.TELNYX_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ assistant_id: env.TELNYX_ASSISTANT_ID })
});
}
return new Response('ok');
}
};
Worker env vars needed: TELNYX_API_KEY, TELNYX_ASSISTANT_ID
Deploy: wrangler deploy (set secrets via wrangler secret put TELNYX_API_KEY)
Config Schema (.voice/config.json)
{
"platform": "telnyx",
"assistant_id": "",
"call_control_app_id": "",
"phone_number": "",
"worker_url": "",
"api_key_placeholder": "TELNYX_API_KEY",
"system_prompt_path": ".voice/system-prompt.txt"
}
Fields written by cks:voice-setup agent after provisioning via MCP.
phone_number and assistant_id are filled in after creation — no real API keys stored.
MCP Provisioning Sequence
The cks:voice-setup agent runs these in order:
1. list_ai_assistants → check if CKS assistant already exists
2. create_ai_assistants → create with system prompt from .voice/system-prompt.txt
3. list_available_phone_numbers → filter by user's country, show options
4. [User selects number]
5. create_call_control_applications → webhook_event_url = Cloudflare Worker URL
6. Write .voice/config.json with assistant_id + call_control_app_id
7. Scaffold .voice/worker.js + wrangler.toml
8. Show deployment instructions
Vapi.ai / ElevenLabs (fallback — no MCP)
Only if user explicitly prefers these. Setup remains manual (no MCP provisioning).
See previous version of this file for setup steps. Not recommended — Telnyx MCP is faster.
Common Rationalizations
| Rationalization | Reality |
|---|
| "I still need n8n for the bridge" | Telnyx AI Assistant handles STT + LLM + TTS natively. Cloudflare Worker just starts it — 15 lines. |
| "The Cloudflare Worker is still an external dependency" | It's 15 lines and deploys in 30 seconds with wrangler deploy. Simpler than any n8n workflow. |
| "I can commit the API key for testing" | Voice API keys are billable. Use wrangler secret put — never commit. |
| "Markdown is fine in voice responses" | Hyphens and asterisks are read aloud literally. Plain text only. |
| "Two sentences is too limiting" | Voice users lose focus after 15 seconds. Brevity is the feature. |
Verification
