Open in

Käytä ThunderPhonea MCP-palvelimena

Rakenna, testaa, validoi ja käytä ThunderPhonen puheagentteja Claudesta, ChatGPT:stä, Claude Codesta, Codexista, Cursorista, VS Codesta tai toisesta Streamable HTTP MCP -asiakasohjelmasta.

ThunderPhone tarjoaa Streamable HTTP Model Context Protocol -palvelimen osoitteessa:

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

Tämä on vastakkainen suunta kuin etä-MCP-palvelimen yhdistäminen puheagenttiin:

Suunta	Tulos
Etä-MCP-palvelin → ThunderPhone-agentti	Puheagentti voi kutsua etäpalvelimen työkaluja.
ThunderPhone → MCP-asiakkaasi	Koodausagenttisi voi rakentaa, testata ja käyttää ThunderPhonea.

Todennus

Käytä OAuthia oletuksena hakemistoasiakkaille: kirjaudu sisään, valitse organisaatio ja hyväksy pyydetyt käyttöoikeudet. Peruuta käyttöoikeus kohdassa Organisaatio → API-avaimet → Valtuutetut sovellukset.

Jos asiakas on määritetty API-avaimella, luo sk_live_-avain kohdassa Organisaatio → Avaimet ja aseta se MCP-asiakkaallesi muuttujaksi THUNDERPHONE_API_KEY. Avain on sidottu yhteen organisaatioon; toisen organisaation omistama tunniste käyttäytyy kuin sitä ei löytyisi.

CLI- ja stdio-vaihtoehdot

ThunderPhone CLI voi kirjoittaa asiakasmäärityksen säilyttäen muut palvelimet ennallaan:

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

Kun @thunderphone/mcp on asennettu globaalisti, käytä thunderphone-mcp setup -komentoa samoilla asetuksilla. Asennus tukee Claude Codea, Codexia, Cursoria, VS Codea, Geminiä, Claude Desktopia ja Windsurfia. Suoraa HTTP:tä suositellaan; Desktop käyttää stdiota.

Määritä mille tahansa stdiota tukevalle asiakkaalle command: "npx" ja args: ["-y", "@thunderphone/mcp"]. Kääre käyttää ensin muuttujaa THUNDERPHONE_API_KEY, sitten thunderphone login -komennon tunnistetietoja ja päivittää vanhentuneet tunnukset, minkä jälkeen se käyttää OAuthia mcp-remote-palvelun kautta. Laitekirjautuminen ja OAuth edellyttävät vastaavaa API:n OAuth-käyttöönottoa. API-avainpolku ei edellytä sitä. Suorat HTTP-määritykset eivät lue CLI-tunnistetietovarastoa; käytä stdio-käärettä hyödyntääksesi laitekirjautumista uudelleen.

Nämä ovat vaihtoehtoja alla oleville manuaalisille asiakasmäärityksille.

Asiakasohjelman määritys

Claude ja ChatGPT kirjautuvat sisään OAuthilla; API-avainta ei tarvita. Jos sinulla ei vielä ole ThunderPhone-tiliä, valitse kirjautumissivulla Luo tili. Sähköpostisi vahvistamisen jälkeen palaat hyväksyntänäyttöön.

Claude (verkko, työpöytä ja mobiili)

Avaa Mukauta → Liittimet (vanhemmissa versioissa Asetukset → Liittimet). Jos ThunderPhone näkyy liitinhakemistossa, valitse se. Muussa tapauksessa valitse Lisää mukautettu liitin, nimeä se ThunderPhone ja anna osoitteeksi https://api.thunderphone.com/v1/mcp.
Valitse Yhdistä, kirjaudu sisään ThunderPhoneen, valitse organisaatio ja hyväksy käyttöoikeudet.
Ota chatissa ThunderPhone käyttöön työkalupainikkeesta ja pyydä tarvitsemaasi, esimerkiksi "Luettele agenttini".

Claude pyytää lupaa ennen kuin se käyttää kutakin työkalua ensimmäisen kerran. Voit ohittaa useimmat näistä kehotteista avaamalla Mukauta → Liittimet → ThunderPhone ja asettamalla Vain luku -työkalut aina sallituiksi. Nämä työkalut vain hakevat tietoja: agentteja, puheluita, transkriptioita, saldoja ja dokumentaatiota. Jätä Kirjoitus-/poistotyökalut hyväksyntää vaativiksi, jos haluat nähdä jokaisen muutoksen ennen sen tapahtumista.

Mukautetut liittimet edellyttävät maksullista Claude-tilausta. Team- ja Enterprise-tilauksissa omistaja lisää liittimen ensin organisaation liitinasetuksissa, minkä jälkeen jokainen jäsen yhdistää oman ThunderPhone-tilinsä.

ChatGPT

Jos ThunderPhone näkyy ChatGPT:n sovellushakemistossa, valitse se ja yhdistä.
Muussa tapauksessa avaa Asetukset → Sovellukset ja liittimet → Lisäasetukset, ota Kehittäjätila käyttöön ja luo liitin URL-osoitteella https://api.thunderphone.com/v1/mcp sekä OAuth-todennuksella.
Kirjaudu sisään ThunderPhoneen, valitse organisaatio ja hyväksy käyttöoikeudet. Lisää ThunderPhone chatiin työkalupainikkeesta.

Agentin tai puhelinnumeron poistaminen, luonnoksen hylkääminen, kampanjan käynnistäminen ja ulkoiseen järjestelmään kirjoittavan testipyynnön lähettäminen edellyttävät toista vahvistusta kummassakin sovelluksessa. Katso Tuhoavien toimintojen vahvistaminen.

Claude Code

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

Codex

Lisää tämä tiedostoon ~/.codex/config.toml:

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

Cursor

Luo .cursor/mcp.json:

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

Claude Desktop

Lisää mcp-remote-silta Claude Desktopin määrityksiin:

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

Luo .vscode/mcp.json ja syötä avain VS Coden syöttökehotteessa:

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

Työkalut

Jokaisella työkalulla on MCP-merkinnät. Taulukoissa R tarkoittaa vain luku -tilaa, D tuhoavaa, I idempotenttia ja O avoimen maailman/verkon vuorovaikutusta. Viiva tarkoittaa, ettei vihjettä ole asetettu.

Yhteys

Työkalu	Keskeiset argumentit	Merkinnät	Mitä se tekee
`get_connection_identity`	—	R, I	Vahvistaa tunnistetiedon ja palauttaa sen organisaation sekä turvalliset tunnistetietometatiedot.

Agentit

Työkalu	Tärkeimmät argumentit	Merkinnät	Toiminto
`list_agents`	—	R, I	Luettelee agentit.
`get_agent`	`agent_id`	R, I	Hakee yhden agentin.
`create_agent`	agentin määritys	—	Luo agentin.
`update_agent`	`agent_id`, muuttuneet kentät	D	Valmistelee kentät agentin luonnokseen ja korvaa luonnoksessa olevat arvot. Suoritetaan ilman vahvistusvaihetta: käyttöön otettu agentti pysyy muuttumattomana, kunnes suoritat `deploy_agent`, ja `discard_agent_draft` palauttaa luonnoksen ennalleen.
`deploy_agent`	`agent_id`, valinnainen `if_updated_at`	D, I	Siirtää luonnoksen tuotantoon.
`discard_agent_draft`	`agent_id`, valinnainen `if_updated_at`, `confirmation_token` toisessa pyynnössä	D, I	Hylkää valmistellut muutokset. Kaksivaiheinen, katso Tuhoavien toimintojen vahvistaminen.
`duplicate_agent`	`agent_id`, valinnainen `name`	—	Kopioi agentin organisaation sisällä.
`delete_agent`	`agent_id`, `confirmation_token` toisessa pyynnössä	D, I	Poistaa agentin pysyvästi. Kaksivaiheinen.
`list_agent_versions`	`agent_id`	R, I	Luettelee käyttöön otetut määritysversiot.

Puhelinnumerot ja operaattorit

Työkalu	Tärkeimmät argumentit	Merkinnät	Toiminto
`list_phone_numbers`	—	R, I	Listaa organisaation numerot ja reitityksen.
`get_phone_number_limits`	—	R, I	Hakee hallinnoitujen numeroiden käytön ja rajat.
`provision_phone_number`	valinnainen `area_code`, `city`, `state`, `idempotency_key`	D, O	Ostaa ThunderPhone-hallinnoidun saapuvan numeron.
`list_voip_connections`	—	R, I	Listaa yhdistetyt asiakkaan operaattorit.
`search_voip_numbers`	`connection_id`, `country`, `type`, valinnainen `area_code`	R, I, O	Hakee operaattorin numerovarastosta.
`import_voip_numbers`	`connection_id`, `numbers`	D, O	Tuo operaattorilla jo omistetut numerot.
`update_phone_number`	`phone_number_id`, reititys-/tunniste-/webhook-kentät	D	Päivittää numeron reitityksen, mukaan lukien agentin määrityksen.
`delete_phone_number`	`phone_number_id`, `confirm`, valinnainen `release_at_provider`, `confirmation_token` toisessa pyynnössä	D, I, O	Vapauttaa numeron. Kaksivaiheinen.

SMS

Työkalu	Tärkeimmät argumentit	Huomautukset	Mitä se tekee
`send_sms`	`from_number`, `to`, `body`, `idempotency_key`	D, I, O	Lähettää yhden pelkkää tekstiä sisältävän tekstiviestin yhdistetyn Twilio- tai Telnyx-numeron kautta.

Puhelut

Työkalu	Keskeiset argumentit	Merkinnät	Toiminto
`list_calls`	valinnaiset suodattimet, `limit`, `offset`	R, I	Listaa puhelut REST-rajapinnan puheluhistorian suodattimilla.
`get_call`	`call_id`	R, I	Hakee puhelun tilan ja metatiedot.
`get_call_transcript`	`call_id`, valinnainen `live`	R, I	Hakee puhelun transkriptin.
`get_call_audio_url`	`call_id`, valinnainen `download`	R, I, O	Palauttaa allekirjoitetun ääni-URL-osoitteen; ääntä ei koskaan suoratoisteta MCP:n kautta.
`get_call_grade`	`call_id`	R, I	Hakee uusimman puheluarvosanan.
`place_call`	`agent_id`, `from_number`, `to_number`	D, O	Soittaa yhden ei-idempotentin lähtevän puhelun.
`export_calls`	puhelusuodattimet, `export_format`	R, I	Vie REST-päätepisteen enimmäismäärään asti JSON- tai CSV-muodossa.

Testaus ja validointi

Työkalu	Tärkeimmät argumentit	Merkinnät	Mitä se tekee
`list_test_scenarios`	`agent_id`	R, I	Luettelee testiskenaariot.
`create_test_scenario`	`agent_id`, `title`, `scenario_prompt`, valinnaiset ehdot	—	Luo skenaarion.
`generate_test_scenarios`	`agent_id`, valinnaiset `count`, `include_edge_cases`, `locale`	O	Luo skenaarioita agentin kehotteen perusteella.
`run_agent_tests`	`agent_id`, `channel`, `consent_to_charge`, valinnainen valinta/matriisi	D, O	Suorittaa skenaariot verkon tai puhelinverkon kautta.
`get_test_run`	`agent_id`, `batch_id`	R, I	Hakee erän tilan ja skenaariokohtaiset tulokset.
`list_validation_runs`	`agent_id`	R, I	Luettelee viimeisimmät luonnoksen validointiajot.
`get_validation_status`	`agent_id`	R, I	Hakee viimeisimmän validointitilan ja luonnosvastaavuuden.

Tietämys

Työkalu	Keskeiset argumentit	Merkinnät	Mitä se tekee
`list_knowledge_bases`	—	R, I	Luettelee tietämyskannat.
`create_knowledge_base`	`name`, valinnainen `description`	—	Luo tietämyskannan.
`add_knowledge_document`	`knowledge_base_id`, `name`, `content`	—	Lisää tekstiä tai Markdownia.
`import_knowledge_url`	`url`, valinnainen `name`	O	Asettaa julkisen sivun jonoon turvallista sisäänottoa varten.
`search_knowledge`	`knowledge_base_id`, `query`	R, I	Hakee tuotantoympäristön haun kautta.

Integraatiot, webhookit ja etä-MCP-palvelimet

Työkalu	Pääargumentit	Huomautukset	Toiminto
`list_integrations`	—	R, I	Listaa HTTP-funktiointegraatiot.
`create_integration`	`display_name`, funktion `spec`, valinnaiset päätepistekentät	—	Luo HTTP-työkalun. Lisää todennusotsakkeet hallintapaneelissa.
`test_integration`	`url`, valinnainen menetelmä/runko/aikakatkaisu, `integration_id` ja `header_names`, `confirmation_token` toisella pyynnöllä	D, O	Lähettää rajatun, SSRF-suojatun testipyynnön. Tallennetut otsakearvot täytetään integraatiosta, ja ne lähetetään vain sen omalle isännälle. `POST` (oletus), `PUT`, `PATCH` ja `DELETE` ovat kaksivaiheisia; `GET` suoritetaan heti.
`list_webhook_endpoints`	—	R, I	Listaa allekirjoitetut webhook-päätepisteet.
`list_webhook_deliveries`	valinnainen `agent_id`, valinnainen `endpoint_id`	R, I	Listaa viimeaikaiset webhook-toimitusten tulokset ilman hyötykuormia.
`create_webhook_endpoint`	`label`, `url`, valinnaiset tapahtumat/tila	O	Luo allekirjoitetun webhook-päätepisteen.
`test_webhook_endpoint`	`endpoint_id`	O	Lähettää synteettisen tapahtuman normaalin toimituksen kautta.
`list_mcp_servers`	—	R, I	Listaa etäpalvelimet, joita puheagentit voivat kutsua.
`create_mcp_server`	`display_name`, `url`	O	Rekisteröi ja synkronoi etäpalvelimen. Todennusotsakkeita tarvitsevat palvelimet lisätään hallintapaneelissa.
`sync_mcp_server_tools`	`server_id`	D, O	Päivittää etäpalvelimen työkaluluettelon.

Kampanjat

Työkalu	Keskeiset argumentit	Merkinnät	Mitä se tekee
`list_campaigns`	—	R, I	Luettelee lähtevät kampanjat.
`create_campaign`	kampanjakentät	—	Luo kampanjaluonnoksen.
`add_campaign_contacts`	`campaign_id`, `contacts`	—	Lisää enintään 5 000 JSON-yhteystietoa.
`campaign_action`	`campaign_id`, `action`, valinnainen `consent_to_charge`, `confirmation_token` toisessa pyynnössä	D, O	Suorittaa `start`, `pause`, `resume` tai `stop`. `start` ja `resume` ovat kaksivaiheisia; `pause` ja `stop` suoritetaan heti.
`get_campaign_stats`	`campaign_id`	R, I	Hakee laskurit ja viimeisimmät tulokset.

Äänet, laskutus ja dokumentaatio

Työkalu	Keskeiset argumentit	Merkinnät	Toiminto
`list_voices`	—	R, I	Listaa äänet ja tuetut kielet.
`preview_voice`	`voice`, `language`, `text`	O	Luo näytteen ja palauttaa allekirjoitetun URL-osoitteen.
`list_voice_clones`	—	R, I	Listaa mukautetut äänikloonit.
`get_billing_summary`	—	R, I	Hakee saldon ja viralliset palvelutasojen hinnat; maksuihin tehtäviä muutoksia ei ole käytettävissä.
`search_docs`	`query`, valinnainen `limit`	R, I, O	Hakee julkisesta dokumentaatiohakemistosta.
`get_doc_page`	`path`	R, I, O	Hakee yhden julkisen Markdown-dokumentaatiosivun.

Kaikki tuotetyökalut käyttävät samoja REST-koodipolkuja kuin julkinen API. REST-validointi, organisaatiorajaus, roolit, laskutuksen hyväksyntä, kiintiöt, TCPA-vahvistus, palveluntarjoajan turvallisuus ja auditointikäyttäytyminen ovat siksi voimassa muuttumattomina.

Tuhoavien toimintojen vahvistaminen

D-merkityt työkalut muuttavat tai poistavat jotain tai aloittavat soitot oikeille ihmisille. Toimintoihin, joita ei voi peruuttaa, tarvitaan kaksi pyyntöä. Ensimmäinen pyyntö ei muuta mitään ja palauttaa:

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

Agentti näyttää käyttäjälle, mihin toiminto vaikuttaa, ja pyytää vahvistuksen. Sen jälkeen se toistaa pyynnön samoilla argumenteilla sekä confirmation_token-arvolla. Tunniste on voimassa 10 minuuttia ja koskee yhtä organisaatiota, yhtä työkalua ja yhtä täsmällistä argumenttijoukkoa, joten kolmen agentin poistaminen vaatii kolme vahvistusta. campaign_action, jossa käytetään arvoa pause tai stop, ohittaa tämän vaiheen, jotta käynnissä oleva kampanja voidaan aina pysäyttää heti. Sama koskee test_integration-toimintoa, jossa käytetään GET-menetelmää. Jotkin D-työkalut suoritetaan yhdellä pyynnöllä, koska D merkitsee niiden vaikutusta, ei palvelinpuolen vahvistusta: update_agent korvaa luonnoksessa olleet tiedot (discard_agent_draft palauttaa ne), deploy_agent korvaa käytössä olevan määrityksen, update_phone_number reitittää käynnissä olevat puhelut uudelleen, sync_mcp_server_tools korvaa etäpalvelimen työkaluluettelon, import_voip_numbers kohdistaa numerot uudelleen operaattoriisi, run_agent_tests voi käyttää saldoa, send_sms ja place_call tavoittavat oikean henkilön (place_call säilyttää oman suostumusvahvistuksensa), ja provision_phone_number ostaa numeron. MCP-asiakkaasi voi silti pyytää sinua hyväksymään nämä toiminnot.

Aloituskehotteet

prompts/list ilmoittaa viidestä uudelleenkäytettävästä työnkulusta:

create_inbound_receptionist
run_agent_tests
buy_and_attach_number
review_low_grade_calls
add_url_to_agent_knowledge

Käytä prompts/get-toimintoa luetellun kehotteen nimellä ja sen määritetyillä argumenteilla saadaksesi käyttövalmiin käyttäjäviestin.

Resurssit

resources/list tarjoaa julkisia välimuistissa olevia viitteitä:

URI	Sisältö
`thunderphone://docs/llms.txt`	Julkisen dokumentaation hakemisto.
`thunderphone://docs/quickstart`	Pika-aloituksen Markdown.
`thunderphone://pricing`	Nykyisen julkisen hinnoittelun Markdown.

Lue yksittäinen resurssi toiminnolla resources/read. Julkisissa hauissa käytetään lyhyttä aikakatkaisua, 2 MiB:n rajaa ja kymmenen minuutin prosessinsisäistä välimuistia.

Protokolla ja virheet

Palvelin tukee protokollaversioita 2025-06-18 ja 2025-03-26; se toistaa tuetun asiakasversion ja valitsee muussa tapauksessa version 2025-06-18. Se toteuttaa initialize-, ping-, työkalut-, kehotteet-, resurssit- ja ilmoitustoiminnot. Ilmoitukset palauttavat 202 Accepted. Tämä tilaton palvelin ei tarjoa SSE-kuuntelijaa eikä istunnon poistoa, joten GET ja DELETE palauttavat virheen 405 Method Not Allowed otsakkeella Allow: POST.

Työkalujen epäonnistumiset pysyvät onnistuneina JSON-RPC-vastauksina, joissa on isError: true. Niiden teksti sisältää lyhyen lauseen, jota seuraa JSON-lohko:

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

Erottuva etuliite outbound_tcpa_confirmation_required: säilytetään toiminnolle place_call. Tuntemattomat JSON-RPC-metodit palauttavat arvon -32601 HTTP-200-vastauksessa. MCP 2025-06-18 ei tue JSON-RPC-eriä, ja ne palauttavat selkeän -32600-virheellisen pyynnön virheen.