Open in

Gunakan ThunderPhone sebagai server MCP

Bangun, uji, validasi, dan operasikan agen suara ThunderPhone dari Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code, atau klien MCP HTTP yang dapat di-streaming lainnya.

ThunderPhone menyediakan server Model Context Protocol HTTP yang dapat di-stream di:

https://api.thunderphone.com/v1/mcp

Ini adalah arah kebalikan dari menghubungkan server MCP jarak jauh ke agen suara:

Arah	Hasil
Server MCP jarak jauh → agen ThunderPhone	Agen suara dapat memanggil alat server jarak jauh.
ThunderPhone → klien MCP Anda	Agen pengodean Anda dapat membangun, menguji, dan mengoperasikan ThunderPhone.

Autentikasi

Gunakan OAuth secara default untuk klien direktori: Masuk, pilih organisasi, dan setujui izin yang diminta. Cabut akses di Organisasi → Kunci API → Aplikasi terotorisasi.

Untuk klien yang dikonfigurasi dengan kunci API, buat kunci sk_live_ di Organisasi → Kunci dan ekspos ke klien MCP Anda sebagai THUNDERPHONE_API_KEY. Kunci tersebut terikat ke satu organisasi; ID yang dimiliki organisasi lain akan dianggap tidak ditemukan.

Alternatif CLI dan stdio

CLI ThunderPhone dapat menulis konfigurasi klien sambil mempertahankan server lain yang tidak terkait:

npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
npx thunderphone mcp setup --client claude-desktop --scope user

Setelah instalasi global @thunderphone/mcp, gunakan thunderphone-mcp setup dengan opsi yang sama. Penyiapan mendukung Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop, dan Windsurf. HTTP langsung lebih disarankan; Desktop menggunakan stdio.

Untuk klien apa pun yang mendukung stdio, konfigurasikan command: "npx" dengan args: ["-y", "@thunderphone/mcp"]. Wrapper menggunakan THUNDERPHONE_API_KEY terlebih dahulu, kemudian kredensial dari thunderphone login, memperbarui token yang kedaluwarsa, lalu OAuth melalui mcp-remote. Login perangkat dan OAuth memerlukan peluncuran OAuth API yang sesuai. Jalur kunci API tidak memerlukannya. Konfigurasi HTTP langsung tidak membaca penyimpanan kredensial CLI; gunakan wrapper stdio untuk menggunakan kembali login perangkat.

Ini adalah alternatif untuk konfigurasi klien manual di bawah.

Konfigurasi klien

Claude dan ChatGPT menggunakan OAuth untuk Masuk; tidak memerlukan kunci API. Jika Anda belum memiliki akun ThunderPhone, pilih Buat akun di halaman masuk, lalu Anda akan kembali ke layar persetujuan setelah memverifikasi email.

Claude (web, desktop, dan seluler)

Buka Sesuaikan → Konektor (Pengaturan → Konektor di versi lama). Jika ThunderPhone muncul di direktori konektor, pilih ThunderPhone. Jika tidak, pilih Tambahkan konektor kustom, beri nama ThunderPhone, lalu masukkan https://api.thunderphone.com/v1/mcp.
Pilih Sambungkan, Masuk ke ThunderPhone, pilih organisasi, lalu setujui izin.
Dalam chat, aktifkan ThunderPhone dari menu alat dan minta apa yang Anda perlukan, misalnya "Tampilkan agen saya".

Claude meminta persetujuan sebelum menggunakan setiap alat untuk pertama kalinya. Untuk melewati sebagian besar prompt tersebut, buka Sesuaikan → Konektor → ThunderPhone dan atur Alat baca-saja agar selalu diizinkan. Alat tersebut hanya mencari informasi: agen, panggilan, transkrip, saldo, dokumentasi. Biarkan Alat tulis/hapus memerlukan persetujuan jika Anda ingin melihat setiap perubahan sebelum terjadi.

Konektor kustom memerlukan paket Claude berbayar. Pada paket Team dan Enterprise, pemilik harus menambahkan konektor terlebih dahulu di pengaturan konektor organisasi, lalu setiap anggota menyambungkan akun ThunderPhone mereka sendiri.

ChatGPT

Jika ThunderPhone muncul di direktori aplikasi ChatGPT, pilih ThunderPhone dan sambungkan.
Jika tidak, buka Pengaturan → Aplikasi & Konektor → Pengaturan lanjutan, aktifkan Mode pengembang, lalu buat konektor dengan URL https://api.thunderphone.com/v1/mcp dan autentikasi OAuth.
Masuk ke ThunderPhone, pilih organisasi, lalu setujui izin. Tambahkan ThunderPhone ke chat dari menu alat.

Menghapus agen atau nomor telepon, membuang draf, meluncurkan kampanye, dan mengirim permintaan pengujian yang dapat menulis ke sistem eksternal memerlukan konfirmasi kedua di salah satu aplikasi; lihat Mengonfirmasi tindakan destruktif.

Claude Code

claude mcp add --transport http thunderphone https://api.thunderphone.com/v1/mcp \
  --header "Authorization: Bearer $THUNDERPHONE_API_KEY"

Codex

Tambahkan ini ke ~/.codex/config.toml:

[mcp_servers.thunderphone]
url = "https://api.thunderphone.com/v1/mcp"
bearer_token_env_var = "THUNDERPHONE_API_KEY"

Cursor

Buat .cursor/mcp.json:

{
  "mcpServers": {
    "thunderphone": {
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}

Claude Desktop

Tambahkan bridge mcp-remote ke konfigurasi Claude Desktop:

{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.thunderphone.com/v1/mcp",
        "--header",
        "Authorization: Bearer ${THUNDERPHONE_API_KEY}"
      ],
      "env": {
        "THUNDERPHONE_API_KEY": "sk_live_YOUR_API_KEY"
      }
    }
  }
}

VS Code

Buat .vscode/mcp.json dan masukkan kunci melalui prompt input VS Code:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "thunderphone-api-key",
      "description": "ThunderPhone organization API key",
      "password": true
    }
  ],
  "servers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:thunderphone-api-key}"
      }
    }
  }
}

Alat

Setiap alat memiliki anotasi MCP. Dalam tabel, R berarti hanya-baca, D destruktif, I idempoten, dan O interaksi dunia terbuka/jaringan. Tanda hubung berarti tidak ada petunjuk yang ditetapkan.

Koneksi

Alat	Argumen utama	Anotasi	Fungsinya
`get_connection_identity`	—	R, I	Memvalidasi kredensial dan mengembalikan organisasi serta metadata kredensial yang aman.

Agen

Alat	Argumen utama	Anotasi	Fungsinya
`list_agents`	—	R, I	Mencantumkan agen.
`get_agent`	`agent_id`	R, I	Mendapatkan satu agen.
`create_agent`	konfigurasi agen	—	Membuat agen.
`update_agent`	`agent_id`, bidang yang diubah	D	Menyimpan bidang dalam draf agen, menggantikan isi draf sebelumnya. Berjalan tanpa langkah konfirmasi: agen yang telah di-deploy tidak berubah hingga `deploy_agent`, dan `discard_agent_draft` mengembalikan draf.
`deploy_agent`	`agent_id`, `if_updated_at` opsional	D, I	Mempromosikan draf ke produksi.
`discard_agent_draft`	`agent_id`, `if_updated_at` opsional, `confirmation_token` pada permintaan kedua	D, I	Membuang perubahan yang disimpan. Dua langkah, lihat Mengonfirmasi tindakan destruktif.
`duplicate_agent`	`agent_id`, `name` opsional	—	Menyalin agen di dalam organisasi.
`delete_agent`	`agent_id`, `confirmation_token` pada permintaan kedua	D, I	Menghapus agen secara permanen. Dua langkah.
`list_agent_versions`	`agent_id`	R, I	Mencantumkan versi konfigurasi yang telah di-deploy.

Nomor telepon dan operator

Alat	Argumen utama	Anotasi	Fungsinya
`list_phone_numbers`	—	R, I	Mencantumkan nomor organisasi dan perutean.
`get_phone_number_limits`	—	R, I	Mendapatkan penggunaan dan batas nomor yang dikelola.
`provision_phone_number`	opsional `area_code`, `city`, `state`, `idempotency_key`	D, O	Membeli nomor masuk yang dikelola ThunderPhone.
`list_voip_connections`	—	R, I	Mencantumkan operator pelanggan yang terhubung.
`search_voip_numbers`	`connection_id`, `country`, `type`, opsional `area_code`	R, I, O	Mencari inventaris operator.
`import_voip_numbers`	`connection_id`, `numbers`	D, O	Mengimpor nomor yang sudah dimiliki di operator.
`update_phone_number`	`phone_number_id`, kolom perutean/label/webhook	D	Memperbarui perutean nomor, termasuk penetapan agen.
`delete_phone_number`	`phone_number_id`, `confirm`, opsional `release_at_provider`, `confirmation_token` pada permintaan kedua	D, I, O	Melepaskan nomor. Dua langkah.

SMS

Alat	Argumen utama	Anotasi	Fungsinya
`send_sms`	`from_number`, `to`, `body`, `idempotency_key`	D, I, O	Mengirim satu SMS teks biasa melalui nomor Twilio atau Telnyx yang terhubung.

Panggilan

Alat	Argumen utama	Anotasi	Fungsinya
`list_calls`	filter opsional, `limit`, `offset`	R, I	Mencantumkan panggilan dengan filter riwayat panggilan REST.
`get_call`	`call_id`	R, I	Mendapatkan Status dan metadata panggilan.
`get_call_transcript`	`call_id`, `live` opsional	R, I	Mendapatkan transkrip panggilan.
`get_call_audio_url`	`call_id`, `download` opsional	R, I, O	Mengembalikan URL audio bertanda tangan; audio tidak pernah di-stream melalui MCP.
`get_call_grade`	`call_id`	R, I	Mendapatkan penilaian panggilan terbaru.
`place_call`	`agent_id`, `from_number`, `to_number`	D, O	Melakukan satu panggilan keluar non-idempoten.
`export_calls`	filter panggilan, `export_format`	R, I	Mengekspor hingga batas endpoint REST sebagai JSON atau CSV.

Pengujian dan validasi

Alat	Argumen utama	Anotasi	Fungsinya
`list_test_scenarios`	`agent_id`	R, I	Mencantumkan skenario pengujian.
`create_test_scenario`	`agent_id`, `title`, `scenario_prompt`, kondisi opsional	—	Membuat skenario.
`generate_test_scenarios`	`agent_id`, `count` opsional, `include_edge_cases`, `locale`	O	Menghasilkan skenario dari Prompt agen.
`run_agent_tests`	`agent_id`, `channel`, `consent_to_charge`, pilihan/matriks opsional	D, O	Menjalankan skenario melalui web atau telepon.
`get_test_run`	`agent_id`, `batch_id`	R, I	Mendapatkan Status batch dan hasil per skenario.
`list_validation_runs`	`agent_id`	R, I	Mencantumkan proses validasi draf terbaru.
`get_validation_status`	`agent_id`	R, I	Mendapatkan status validasi terbaru dan kecocokan draf.

Pengetahuan

Alat	Argumen utama	Anotasi	Fungsinya
`list_knowledge_bases`	—	R, I	Mencantumkan basis pengetahuan.
`create_knowledge_base`	`name`, opsional `description`	—	Membuat basis pengetahuan.
`add_knowledge_document`	`knowledge_base_id`, `name`, `content`	—	Menambahkan teks atau Markdown.
`import_knowledge_url`	`url`, opsional `name`	O	Mengantrikan halaman publik untuk penyerapan yang aman.
`search_knowledge`	`knowledge_base_id`, `query`	R, I	Mencari melalui pengambilan produksi.

Integrasi, webhook, dan server MCP jarak jauh

Alat	Argumen utama	Anotasi	Fungsinya
`list_integrations`	—	R, I	Mencantumkan integrasi fungsi HTTP.
`create_integration`	`display_name`, `spec` fungsi, kolom endpoint opsional	—	Membuat alat HTTP. Tambahkan header autentikasi di dashboard.
`test_integration`	`url`, metode/badan/waktu tunggu opsional, `integration_id` dengan `header_names`, `confirmation_token` pada permintaan kedua	D, O	Mengirim permintaan pengujian yang dibatasi dan dilindungi SSRF. Nilai header yang disimpan diisi dari integrasi dan hanya dikirim ke host-nya sendiri. `POST` (default), `PUT`, `PATCH`, dan `DELETE` menggunakan dua tahap; `GET` langsung dijalankan.
`list_webhook_endpoints`	—	R, I	Mencantumkan endpoint webhook yang ditandatangani.
`list_webhook_deliveries`	`agent_id` opsional, `endpoint_id` opsional	R, I	Mencantumkan hasil pengiriman webhook terbaru tanpa payload.
`create_webhook_endpoint`	`label`, `url`, peristiwa/Status opsional	O	Membuat endpoint webhook yang ditandatangani.
`test_webhook_endpoint`	`endpoint_id`	O	Mengirim peristiwa sintetis melalui pengiriman normal.
`list_mcp_servers`	—	R, I	Mencantumkan server jarak jauh yang dapat dipanggil oleh agen suara AI.
`create_mcp_server`	`display_name`, `url`	O	Mendaftarkan dan menyinkronkan server jarak jauh. Server yang memerlukan header autentikasi ditambahkan di dashboard.
`sync_mcp_server_tools`	`server_id`	D, O	Memperbarui katalog alat server jarak jauh.

Kampanye

Alat	Argumen utama	Anotasi	Fungsinya
`list_campaigns`	—	R, I	Mencantumkan kampanye keluar.
`create_campaign`	bidang kampanye	—	Membuat draf kampanye.
`add_campaign_contacts`	`campaign_id`, `contacts`	—	Menambahkan hingga 5.000 kontak JSON.
`campaign_action`	`campaign_id`, `action`, opsional `consent_to_charge`, `confirmation_token` pada permintaan kedua	D, O	Menjalankan `start`, `pause`, `resume`, atau `stop`. `start` dan `resume` memerlukan dua langkah; `pause` dan `stop` dijalankan segera.
`get_campaign_stats`	`campaign_id`	R, I	Mendapatkan penghitung dan hasil terbaru.

Suara, penagihan, dan dokumentasi

Alat	Argumen utama	Anotasi	Fungsinya
`list_voices`	—	R, I	Mencantumkan suara dan bahasa yang didukung.
`preview_voice`	`voice`, `language`, `text`	O	Membuat sampel dan mengembalikan URL bertanda tangan.
`list_voice_clones`	—	R, I	Mencantumkan klon suara kustom.
`get_billing_summary`	—	R, I	Mendapatkan saldo dan harga tingkatan yang otoritatif; tidak ada mutasi pembayaran yang tersedia.
`search_docs`	`query`, opsional `limit`	R, I, O	Mencari indeks dokumentasi publik.
`get_doc_page`	`path`	R, I, O	Mengambil satu halaman dokumentasi Markdown publik.

Semua alat produk menggunakan jalur kode REST yang sama dengan API publik. Karena itu, validasi REST, cakupan organisasi, peran, penerimaan penagihan, kuota, konfirmasi TCPA, keamanan provider, dan perilaku audit berlaku tanpa perubahan.

Mengonfirmasi tindakan destruktif

Tool yang ditandai D mengubah atau menghapus sesuatu, atau mulai menelepon orang sungguhan. Tool yang tidak dapat dibatalkan memerlukan dua permintaan. Permintaan pertama tidak mengubah apa pun dan mengembalikan:

{
  "status": "confirmation_required",
  "action": "Delete agent",
  "target": { "id": 195, "name": "Front Desk Receptionist" },
  "confirmation_token": "…",
  "expires_in_seconds": 600,
  "next_step": "…"
}

Agen menampilkan kepada pengguna apa yang akan terdampak dan meminta persetujuan. Kemudian, agen mengulangi permintaan dengan argumen yang sama ditambah confirmation_token. Token berlaku selama 10 menit dan mencakup satu organisasi, satu tool, serta satu set argumen yang persis sama, sehingga menghapus tiga agen memerlukan tiga konfirmasi. campaign_action dengan pause atau stop melewati langkah ini agar kampanye yang berjalan selalu dapat dihentikan segera, begitu pula test_integration dengan GET. Beberapa tool D berjalan dalam satu permintaan karena D menandai efeknya, bukan konfirmasi di sisi server: update_agent menggantikan isi draf (discard_agent_draft mengembalikannya), deploy_agent menggantikan konfigurasi aktif, update_phone_number mengarahkan ulang panggilan aktif, sync_mcp_server_tools menggantikan katalog tool server jarak jauh, import_voip_numbers mengarahkan ulang nomor ke operator Anda, run_agent_tests dapat menggunakan kredit, send_sms dan place_call menghubungi orang sungguhan (place_call mempertahankan konfirmasi persetujuannya sendiri), dan provision_phone_number membeli nomor. Klien MCP Anda mungkin tetap meminta Anda untuk menyetujuinya.

Prompt awal

prompts/list menyediakan lima alur kerja yang dapat digunakan kembali:

create_inbound_receptionist
run_agent_tests
buy_and_attach_number
review_low_grade_calls
add_url_to_agent_knowledge

Gunakan prompts/get dengan nama Prompt yang tercantum dan argumen yang dideklarasikannya untuk menerima pesan pengguna yang siap dijalankan.

Sumber daya

resources/list menyediakan referensi publik yang di-cache:

URI	Konten
`thunderphone://docs/llms.txt`	Indeks dokumentasi publik.
`thunderphone://docs/quickstart`	Markdown mulai cepat.
`thunderphone://pricing`	Markdown harga publik saat ini.

Baca salah satunya dengan resources/read. Pengambilan publik menggunakan waktu tunggu singkat, batas 2 MiB, dan cache dalam proses selama sepuluh menit.

Protokol dan error

Server mendukung versi protokol 2025-06-18 dan 2025-03-26; server menggemakan versi klien yang didukung dan selain itu memilih 2025-06-18. Server mengimplementasikan initialize, ping, alat, Prompt, sumber daya, dan notifikasi. Notifikasi mengembalikan 202 Accepted. Server stateless ini tidak menyediakan listener SSE atau penghapusan sesi, sehingga GET dan DELETE mengembalikan 405 Method Not Allowed dengan Allow: POST.

Kegagalan alat tetap berupa respons JSON-RPC yang berhasil dengan isError: true. Teksnya berisi kalimat singkat diikuti blok JSON:

{
  "code": "insufficient_balance",
  "detail": "There is not enough prepaid balance.",
  "next_step": "Call get_billing_summary, add funds in Organization > Billing, then retry."
}

Prefiks berbeda outbound_tcpa_confirmation_required: tetap dipertahankan untuk place_call. Metode JSON-RPC yang tidak dikenal mengembalikan -32601 dalam respons HTTP 200. Batch JSON-RPC tidak didukung oleh MCP 2025-06-18 dan mengembalikan error permintaan tidak valid -32600 yang bersih.