---
title: "Käytä ThunderPhonea MCP-palvelimena"
description: "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:

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

Tämä on vastakkainen suunta kuin [etä-MCP-palvelimen yhdistäminen puheagenttiin](/fi/guides/mcp-servers):

| 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](/fi/guides/oauth) 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.

<Warning>
  `sk_live_`-avain voi lukea organisaation tietoja ja suorittaa tuotantotoimintoja, kuten julkaista agentteja, soittaa puheluita, ostaa numeroita, käynnistää kampanjoita ja poistaa resursseja. Älä sisällytä sitä selainkoodiin, tietovarastoihin, kuvakaappauksiin tai keskustelulokeihin. Käytä asiakkaasi salaisuuksien tallennusta tai ympäristömuuttujatukea ja peruuta paljastunut avain välittömästi.
</Warning>

## CLI- ja stdio-vaihtoehdot

[ThunderPhone CLI](/fi/guides/cli) voi kirjoittaa asiakasmäärityksen säilyttäen
muut palvelimet ennallaan:

```bash
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](/fi/guides/oauth); 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)

1. 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`.
2. Valitse **Yhdistä**, kirjaudu sisään ThunderPhoneen, valitse organisaatio ja hyväksy käyttöoikeudet.
3. 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

1. Jos ThunderPhone näkyy ChatGPT:n sovellushakemistossa, valitse se ja yhdistä.
2. 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.
3. 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](#confirming-destructive-actions).

### Claude Code

```bash
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`:

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

### Cursor

Luo `.cursor/mcp.json`:

```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:

```json
{
  "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:

```json
{
  "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](#confirming-destructive-actions). |
| `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:

```json
{
  "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:

```json
{
  "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.