Kasuta ThunderPhone

Loo, testi, valideeri ja halda ThunderPhone

ThunderPhone pakub Streamable HTTP Model Context Protocoli serverit aadressil:

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

See on vastupidine suund võrreldes kaughostitud MCP-serveri ühendamisega häälagendiga:

Autentimine#

Kasuta kataloogiklientide jaoks vaikimisi OAuthi: logi sisse, vali organisatsioon ja kiida taotletud õigused heaks. Tühista juurdepääs menüüs Organisatsioon → API-võtmed → Volitatud rakendused. Parooli muutmine või lähtestamine või konto e-posti aadressi muutmine tühistab samuti ühenduse, seega ühenda klient pärast seda uuesti.

API-võtmega seadistatud klientide jaoks loo jaotises Organisatsioon → Võtmed sk_live_-võti ja ava see oma MCP-kliendile muutujana THUNDERPHONE_API_KEY. Võti on seotud ühe organisatsiooniga; teisele organisatsioonile kuuluv ID käitub nagu seda ei leitaks.

Organisatsioonid, kes töötlevad PHI-d#

Kui sinu organisatsiooni kõned võivad sisaldada kaitstud terviseteavet (PHI), kuna sul on ThunderPhone’iga BAA või sinu agendid on määratud PHI-d töötlema, ei tagasta ülaltoodud URL kunagi kõnesisu: transkripte, salvestisi, hindeid, kõneloendeid, eksporditud andmeid, kampaaniate tulemusi, kõneanalüütikat ja ülevaateid, päriskõnede põhjal loodud vestlusi ega taasesituse tulemusi. Need tööriistad tagastavad vea koodiga code: "phi_content_unavailable". Agentide loomine, testimine ja seadistamine toimib tavapäraselt.

See URL on avalikes assistentide kataloogides loetletud URL, mis ei pruugi PHI-d edastada. Kui sinu organisatsioonil on assistendi pakkujaga oma BAA, mis katab kasutatava tööruumi:

1. Organisatsiooni administraator avab ThunderPhone’is Organisatsioon → Üldine → AI-assistendi juurdepääs ja kinnitab selle katvuse.
2. Ühenda assistent kohandatud konnektorina hoopis selle URL-iga:

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

Kõnesisu on siis seal saadaval, sealhulgas kõned, mis võivad sisaldada PHI-d. Kinnituse tühistamine peatab selle assistendi järgmisel päringul. Kõne, mida sinu organisatsioon käsitles PHI-d mittesisaldavana, on saadaval mõlemal URL-il.

CLI ja stdio alternatiivid#

ThunderPhone CLI saab kirjutada kliendi konfiguratsiooni, säilitades muud serverid:

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

Pärast paketi @thunderphone/mcp globaalset installimist kasuta sama valikutega käsku thunderphone-mcp setup. Seadistus toetab Claude Code'i, Codexi, Cursorit, VS Code'i, Geminit, Claude Desktopi ja Windsurfi. Eelistatud on otsene HTTP; Desktop kasutab stdio't.

Iga stdio-toega kliendi jaoks seadista command: "npx" koos args: ["-y", "@thunderphone/mcp"]. Ümbris kasutab esmalt muutujat THUNDERPHONE_API_KEY, seejärel käsu thunderphone login autentimisandmeid, värskendades aegunud tokeneid, ning seejärel OAuthi mcp-remote kaudu. Seadmelogimine ja OAuth nõuavad vastavat API OAuthi kasutuselevõttu. API-võtme kasutamine seda ei nõua. Otsesed HTTP-konfiguratsioonid ei loe CLI autentimisandmete hoidlat; seadmelogimise taaskasutamiseks kasuta stdio-ümbrist.

Need on alternatiivid allolevatele käsitsi seadistatavatele kliendikonfiguratsioonidele.

Kliendi seadistamine#

Claude ja ChatGPT kasutavad sisselogimiseks OAuthi; API-võtit ei kasutata. Kui sul veel ThunderPhone'i kontot ei ole, vali sisselogimislehel Loo konto ning pärast e-posti kinnitamist naased kinnitusekraanile.

Claude (veeb, töölauarakendus ja mobiil)#

1. Ava Kohanda → Konnektorid (vanemates versioonides Seaded → Konnektorid). Kui ThunderPhone kuvatakse konnektorite kataloogis, vali see. Vastasel juhul vali Lisa kohandatud konnektor, nimeta see ThunderPhone ja sisesta https://api.thunderphone.com/v1/mcp.
2. Vali Ühenda, logi ThunderPhone'i sisse, vali organisatsioon ja kinnita õigused.
3. Luba vestluses ThunderPhone tööriistade menüüst ja küsi, mida vajad, näiteks „Loetle minu agendid“.

Claude küsib enne iga tööriista esmakordset kasutamist kinnitust. Enamiku nende viipade vahelejätmiseks ava Kohanda → Konnektorid → ThunderPhone ja määra Ainult lugemiseks tööriistad alati lubatuks. Need tööriistad ainult otsivad teavet: agendid, kõned, transkriptsioonid, saldod, dokumentatsioon. Kui soovid iga muudatust enne selle tegemist näha, jäta Kirjutamis-/kustutustööriistad kinnitust nõudma.

Kohandatud konnektorid nõuavad tasulist Claude'i paketti. Team- ja Enterprise-pakettides lisab omanik konnektori esmalt organisatsiooni konnektorite seadetes ning seejärel ühendab iga liige oma ThunderPhone'i konto.

ChatGPT#

1. Kui ThunderPhone kuvatakse ChatGPT rakenduste kataloogis, vali see ja ühenda.
2. Vastasel juhul ava Seaded → Rakendused ja konnektorid → Täpsemad seaded, lülita sisse Arendajarežiim ning loo konnektor URL-iga https://api.thunderphone.com/v1/mcp ja OAuth-autentimisega.
3. Logi ThunderPhone'i sisse, vali organisatsioon ja kinnita õigused. Lisa ThunderPhone vestlusse tööriistade menüüst.

Häälagendi või telefoninumbri kustutamine, mustandi hülgamine, kampaania käivitamine ja välisesse süsteemi kirjutada võiva testpäringu saatmine nõuavad mõlemas rakenduses teist kinnitust; vaata hävitavate toimingute kinnitamine.

Claude Code#

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

Codex#

Lisa see faili ~/.codex/config.toml:

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

Cursor#

Loo .cursor/mcp.json:

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

Claude Desktop#

Lisa Claude Desktopi seadistusse mcp-remote-sild:

{
  "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#

Loo .vscode/mcp.json ja sisesta võti VS Code'i sisestusviiba kaudu:

{
  "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}"
      }
    }
  }
}

Tööriistad#

Igal tööriistal on MCP annotatsioonid. Tabelites tähendab R ainult lugemist, D hävitavat toimingut, I idempotentset toimingut ja O avatud maailma-/võrgusuhtlust. Kriips tähendab, et vihjet pole määratud.

Ühendus#

Agendid#

Telefoninumbrid ja operaatorid#

SMS#

Kõned#

Testimine ja valideerimine#

Agendi iteratsioonitööriistakomplekti vajavateks märgitud tööriistad kuuluvad selle hulka; tööriistakomplekt on beetaversiooni ajal lubatud organisatsioonipõhiselt ning ilma selleta tagastavad need feature_not_enabled koos järgmiste juhistega. Agendi iga vestlus kuulub kas arendus- või testjaotusse. Testjaotus on muudatuse mõõtmiseks, mitte selle häälestamiseks, seega tagastavad vestlustööriistad testjaotuse vestluse kohta ainult selle ID, jaotuse, allika, oleku ja arvud. Testjaotuse taasesituse käitus taasesitab ühe tervikliku testkohordi (sample_size ja sample_seed eiratakse), käitades iga näite selle andmete lubatud mootoril, mis määratakse enne käitust näite põhjal (salvestatud helistaja heli puhul täpne, ainult tekstiga näite puhul tekst; muu konfiguratsiooni kui Bolt v2 puhul täpne tee puudub, seega salvestatud heliga kohort lükatakse selle puhul tagasi koodiga test_needs_exact_replay ja jääb kasutamata; engine jäetakse ära või määratakse auto, kuna exact või text lükatakse tagasi koodiga test_engine_per_example ning midagi ei lange tagasi tekstile), ja tagastab ainult koondandmed mootori kaupa: läbimise määr, tõrked raskusastme ja liigi järgi, latentsus ning kulu. Esimene taasesituse salvestav tulemus kulutab kohordi, seega järgmine testikäitus kasutab mis tahes viiba puhul järgmist kohorti ning kui neid pole alles, lükatakse see tagasi koodiga no_test_cohort (kõnede importimine või vestluste genereerimine täidab uued kohordid); käitus, mis lõpeb enne taasesituse salvestamist (Core ei saa selle helinäiteid täpselt taasesitada, exact_replay_unavailable, selle taasesitusvõimekus on hõivatud, core_busy, või iga käik ületas eelarve, replay_budget_exhausted), jätab kohordi kasutamata. Arendusjaotuses langeb täpne taasesitus, mida Core ei saa käitada, tagasi tekstile ning käitus märgitakse kui degraded. Võrdlused toimivad ainult arendusjaotuses. Iga tasuline tööriist võtab vastu oma proovikäivituse quote_id, mis kehtib ühe käituse jaoks: see kulutatakse püsivalt üks kord käituse alustamisel ning enne seda tagasi lükatud või nurjunud alustamine jätab selle kasutatavaks; pärast seda nurjunud käitus annab sellest teada ning seda korratakse uue proovikäivitusega uue quote_id jaoks. OAuthi korral vajavad review_prompt ja refactor_prompt õigust agents:write, sealhulgas proovikäivitused, ning vestlus- ja taasesitustööriistad vajavad käitamiseks õigust testing:write. Inimesed näevad juhtpaneelil kogu testjaotust. Kõne, mille helistaja on agendi testjaotuses, jäetakse välja, sest see on osa testandmestikust. Tööriistakomplektiga organisatsioonis tagastavad list_calls, get_call, get_call_transcript, get_call_audio_url, get_call_grade ja export_calls selle täpselt kujul {"call_id", "start_time", "held_out": true} (ekspordi ridades on start_time asemel started_at), ilma transkriptsiooni, salvestise, ajaloo, hinde või aruandeta; kõik muud kõne väljad puuduvad, seega tuvasta väljajäetud rida enne kõike muud selle held_out väärtuse järgi. REST API teeb API-võtmete ja OAuthi tokenite puhul sama ning selle paljusid kõnesid hõlmavad vaated (aruannete kokkuvõtted, probleemiklastrid, uurimised, konveieriaruanded) jätavad väljajäetud kõned oma arvudest, klastritest ja valimitest välja ning varjavad mudeli nendest kirjutatud teksti. Väljajäetud kõne kirjutustoiming (hindamine, selle tõstmine testistsenaariumiks, käigu uuesti genereerimine) lükatakse tagasi koodiga held_out_call. Testistsenaarium, mille keegi tõstis väljajäetud kõnest, tagastatakse list_test_scenarios kaudu ja testikäitustes täpselt kujul {"id", "held_out": true}, ning sellest pärit simulatsioonikäitus tagastatakse get_test_run ja simulatsioonitööriistade kaudu täpselt kujul {"id", "scenario_id", "held_out": true}; ka selle simuleeritud kõned jäetakse välja, kuid testikäitused käitavad selle siiski. Arendusvestlus, näide või taasesituse tulemus, mis on kopeeritud väljajäetud helistaja kõnest (jaotused on agendipõhised, seega võib see helistaja kuuluda teise agendi testjaotusse), käitub nagu testjaotuse oma. Inimesed näevad juhtpaneelil väljajäetud kõnesid täielikult ning administraator saab lubada ühel API-võtmel neid täielikult näha (include_held_out_calls, vaikimisi välja lülitatud, määratav ainult juhtpaneelil) integratsiooni jaoks, mis vajab iga kõnet; MCP ei kasuta seda kunagi. Veebihaagid ei muutu. Tööriistakomplektita organisatsioonid ei näe välja held_out ega muid muudatusi.

generate_conversations, import_conversations ja refresh_conversations kasutavad mudelikrediite. Esmalt kutsu neid parameetriga dry_run: true: vastuseks on etapiviisiline kulupakkumine koos quote_id-ga ja midagi ei käivitata. Pakkumine arvestab iga päringuga, mida käitus võib tavapärase mahu juures teha. Tegelik käitus vajab seda quote_id-d (see aegub 15 minuti pärast ja toimib ainult samade argumentidega) ning max_cost_cents-i, mis on range ülempiir: enne iga päringut jätab töö reservi suurima summa, mida see päring võib maksta, ning peatub sobimatu päringu saatmise asemel, säilitades juba kirjutatu. Selle reservi tõttu võib käitus peatuda nii, et osa ülempiirist jääb kasutamata; pakkumise largest_reservation_cents näitab, kui palju varu jätta. Simuleeritud helistajad luuakse agendi viibast; style: "adversarial" loob keerulisi helistajaid, kes survestavad viiba nõrku kohti, ning need vestlused lähevad alati arendusjaotusse. target: "changed_behaviors" suunab helistajad viimases viibamuudatuses muutunu juurde. Iga agent käitab korraga üht neist töödest või üht taasesituskäivitust, seega ei muuda värskendus kunagi näiteid, millel taasesitus töötab; teise töö käimise ajal käivitamine tagastab job_active, replay_run_active või conversation_job_active koos teabega, mida oodata.

Pärast käitumise lisamist, eemaldamist või muutmist sisaldavat viibamuudatust teatab agendi mustandi review_prompt, kui palju testvestlusi kirjutati muude käitumistega viiba jaoks (conversations.refresh_suggested). Seejärel ajakohastab refresh_conversations need mustandi järgi, et arendus- ja testkogum mõõdaksid uut viipa vestlusajalugudel, mida see oleks võinud luua. Värskendus ei kaota kunagi midagi: iga vestlus säilitab kõik varasemad redaktsioonid ning eemaldatud reegli naasmisel taastatakse redaktsioon ajast, mil see olemas oli, koos helistaja tegeliku heliga. Kodeerimisagendi käivitatud värskendus jätab testjaotuse vestlused ja kõrvale jäetud kõnedest kopeeritud vestlused oma valikust, pakkumisest, edenemisest ja kulust välja; ühe neist määramine parameetris conversation_ids tagastab 403 test_conversation. Inimene värskendab neid juhtpaneelilt ning kodeerimisagentidele kuvatakse selle töö tulemustes need ainult ID-de ja arvudena. active näide, mille ajaloo, vastuse või vastusevõtme värskendus ümber kirjutab, läheb tagasi olekusse pending_review märgistusega refreshed_needs_review. Värskenduse pakkumine hinnastab iga loetavat vestlust nii, nagu see kirjutataks ümber, ja iga mudelikõnet selle väljundi ülempiiri alusel ning kehtib viiba ja vestluste kohta, mille põhjal pakkumine koostati: kui kumbki enne käitust muutub, küsi uus pakkumine; kui viip muutub käituse ajal, peatub töö olekuga failed, säilitades värskendatu.

Teadmised#

Integratsioonid, webhookid ja kaug-MCP-serverid#

Kampaaniad#

Organisatsiooni seaded ja blokeeritud helistajad#

get_org_settings, update_org_settings ja get_account_limits vajavad org:read või org:write OAuthi õigust; ühendusel, mis loodi enne nende olemasolu, palutakse see esmakordsel kasutamisel heaks kiita.

Võimalused, abi ja importimine#

Hääled, arveldus ja dokumentatsioon#

Häälagendi, kõne, numbri, kampaania või seadistuse tulemused sisaldavad vastava juhtpaneeli lehe web_url-i, nii et saad selle ThunderPhone’is avada või Zeusiga seal jätkata.

Kõik tootetööriistad kasutavad samu REST-kooditeid nagu avalik API. Seetõttu kehtivad REST-i valideerimine, organisatsioonipõhine ulatus, rollid, arvelduse lubamine, kvoodid, TCPA kinnitus, teenusepakkuja turvalisus ja auditeerimiskäitumine muutmata kujul.

Viipa muutmine kohapeal#

update_agent saab muuta mustandi viiba osa, ilma et peaksid kogu teksti tagasi saatma. prompt_edits on järjestatud otsi-ja-asenda paaride loend samas vormingus, mille tagastavad review_prompt ja refactor_prompt:

{
  "agent_id": 123,
  "expected_prompt_sha256": "9c1f…",
  "prompt_edits": [
    {
      "find": "Ask for their name and their phone number, then tell them we will call back.",
      "replace": "Tell them we will call back, then ask for their name. Once they answer, ask for their phone number."
    }
  ]
}

Server rakendab muudatused järjekorras agendi praegusele mustandviibale (avaldatud viibale, kui mustand puudub) ja kirjutab tulemuse mustandisse sama teed pidi nagu kogu viiba update_agent-iga uuendamisel. Iga find peab selle muudatuse rakendamise hetkel viibas esinema täpselt üks kord. Kui see nii ei ole, ei kirjutata midagi ja tõrge nimetab muudatuse:

expected_prompt_sha256 on valikuline ja kaitseb ka kogu viiba kirjutamist. Kasuta review_prompt-ist saadud väärtust prompt_sha256 või refactor_prompt-ist saadud väärtust source_prompt_sha256. Iga viipa muutev päring tagastab uue teksti prompt_sha256, väärtuse previous_prompt_sha256, kui server luges kõigepealt mustandit, ning next_step, mis soovitab kasutada review_prompt-i, määrates previous_prompt väärtuseks muutmiseelse teksti. REST API võtab vastu ainult kogu viiba: PATCH /v1/agents/{agent_id} koos väärtustega prompt ja if_updated_at.

Hävitavate toimingute kinnitamine#

D-tähisega tööriistad muudavad või eemaldavad midagi või alustavad päris inimestele helistamist. Tagasivõtmatud toimingud nõuavad kahte päringut. Esimene päring ei muuda midagi ja tagastab:

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

Assistent näitab kasutajale, mida see mõjutab, ja palub kinnitust. Seejärel kordab ta päringut samade argumentidega ning lisab confirmation_token. Token kehtib 10 minutit, toimib ühe korra (ka siis, kui see kutse nurjub) ning hõlmab üht organisatsiooni, üht inimest, üht tööriista ja üht täpset argumentide kogumit, seega nõuab kolme agendi kustutamine kolme kinnitust. campaign_action väärtusega pause või stop jätab selle sammu vahele, et käimasoleva kampaania saaks alati kohe peatada; sama kehtib test_integration kohta väärtusega GET. Mõni D-tööriist käivitub ühe päringuga, sest D tähistab nende mõju, mitte serveripoolset kinnitust: update_agent asendab mustandis olnud sisu (discard_agent_draft taastab selle), deploy_agent asendab aktiivse konfiguratsiooni, update_phone_number suunab aktiivsed kõned ümber, sync_mcp_server_tools asendab kaugserveri tööriistakataloogi, import_voip_numbers suunab numbrid ümber sinu operaatorile, run_agent_tests ja run_simulation võivad kulutada krediiti, send_sms ja place_call jõuavad päris inimeseni (place_call säilitab oma nõusolekukinnituse) ning provision_phone_number ostab numbri. test_my_agent kulutab testkrediiti ja vajab consent_to_charge. Ka run_replays kulutab raha; selle dry_run hinnapakkumine ja max_cost_cents ülempiir asendavad kinnitust. Sinu MCP-klient võib siiski paluda sul need heaks kiita.

Mõned tagasipööratavad muudatused ootavad siiski kinnitust: alati block_callers, unblock_callers ja save_voip_setup; update_org_settings, kui see lülitab hoiatuse välja või lisab testnumbri; ning update_agent, kui selle attention_reasons lülitavad välja mõne agendi hoiatuse. Nende next_step palub sul kinnitada täpse muudatuse, mitte ei hoiata, et seda ei saa tagasi võtta.

Alustavad päringud#

prompts/list pakub kaksteist korduskasutatavat töövoogu:

• create_inbound_receptionist
• run_agent_tests
• buy_and_attach_number
• review_low_grade_calls
• add_url_to_agent_knowledge
• improve_agent_from_calls
• check_change_before_deploy
• test_my_agent
• diagnose_phone_number
• why_campaign_not_calling
• call_report
• import_agents

Kasuta käsku prompts/get koos loetletud päringu nime ja selle deklareeritud argumentidega, et saada käivitamisvalmis kasutajasõnum.

Ressursid#

resources/list pakub avalikke vahemällu salvestatud viiteid:

Loe ressurssi käsuga resources/read. Avalikud toomispäringud kasutavad lühikest ajalõppu, 2 MiB piirangut ja kümneminutilist protsessisisest vahemälu.

Protokoll ja vead#

Server toetab protokolliversioone 2025-06-18 ja 2025-03-26; see peegeldab tagasi toetatud kliendiversiooni ning muul juhul valib 2025-06-18. See rakendab meetodeid initialize, ping, tööriistu, päringuid, ressursse ja teavitusi. Teavitused tagastavad 202 Accepted. See olekuta server ei paku SSE-kuulajat ega seansi kustutamist, seega tagastavad GET ja DELETE vastuse 405 Method Not Allowed koos päisega Allow: POST.

Tööriista tõrked jäävad edukateks JSON-RPC vastusteks väärtusega isError: true. Nende tekst sisaldab lühikest lauset, millele järgneb JSON-plokk:

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

Eraldi prefiks outbound_tcpa_confirmation_required: säilitatakse käsu place_call jaoks. Tundmatud JSON-RPC meetodid tagastavad HTTP 200 vastuses väärtuse -32601. JSON-RPC pakke MCP 2025-06-18 ei toeta ning need tagastavad korrektse -32600 sobimatu päringu vea.