Open in

A ThunderPhone használata MCP-kiszolgálóként

ThunderPhone hangalapú AI-ügynökök létrehozása, tesztelése, validálása és üzemeltetése Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code vagy más Streamable HTTP MCP-kliens segítségével.

A ThunderPhone egy Streamable HTTP Model Context Protocol-kiszolgálót biztosít ezen a címen:

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

Ez a távoli MCP-kiszolgáló hangalapú AI-ügynökhöz való csatlakoztatásának ellentétes iránya:

Irány	Eredmény
Távoli MCP-kiszolgáló → ThunderPhone-ügynök	Egy hangalapú AI-ügynök meghívhatja a távoli kiszolgáló eszközeit.
ThunderPhone → az Ön MCP-kliense	Az Ön kódoló ügynöke felépítheti, tesztelheti és üzemeltetheti a ThunderPhone-t.

Hitelesítés

Címtárból telepített kliensekhez alapértelmezés szerint használjon OAuthot: jelentkezzen be, válasszon szervezetet, majd hagyja jóvá a kért jogosultságokat. A hozzáférést a Szervezet → API-kulcsok → Engedélyezett alkalmazások alatt vonhatja vissza.

API-kulccsal konfigurált kliensekhez hozzon létre egy sk_live_ kulcsot a Szervezet → Kulcsok alatt, és tegye elérhetővé MCP-kliense számára THUNDERPHONE_API_KEY néven. A kulcs egy szervezethez van kötve; egy másik szervezet tulajdonában lévő azonosítót a rendszer nem találhatóként kezeli.

CLI- és stdio-alternatívák

A ThunderPhone CLI képes klienskonfigurációt írni a nem kapcsolódó kiszolgálók megőrzése mellett:

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

A @thunderphone/mcp globális telepítése után használja a thunderphone-mcp setup parancsot ugyanazokkal a beállításokkal. A telepítés támogatja a Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop és Windsurf klienseket. A közvetlen HTTP az előnyben részesített; a Desktop stdio-t használ.

Bármely stdio-kompatibilis klienshez konfigurálja a command: "npx" beállítást a következővel: args: ["-y", "@thunderphone/mcp"]. A burkoló először a THUNDERPHONE_API_KEY értékét használja, majd a thunderphone login hitelesítő adatait, megújítva a lejárt tokeneket, ezt követően pedig az OAuthot a mcp-remote használatával. Az eszközös bejelentkezés és az OAuth a megfelelő API OAuth-bevezetést igényli. Az API-kulcsos útvonal nem. A közvetlen HTTP-konfigurációk nem olvassák a CLI hitelesítőadat-tárát; az eszközös bejelentkezés újbóli használatához használja a stdio burkolót.

Ezek a lenti manuális klienskonfigurációk alternatívái.

Ügyfélkonfiguráció

A Claude és a ChatGPT OAuth használatával jelentkezik be; nincs szükség API-kulcsra. Ha még nincs ThunderPhone-fiókja, válassza a bejelentkezési oldalon a Fiók létrehozása lehetőséget, majd az e-mail-címe megerősítése után visszatér a jóváhagyási képernyőre.

Claude (web, asztali és mobil)

Nyissa meg a Testreszabás → Csatlakozók menüt (régebbi verziókban: Beállítások → Csatlakozók). Ha a ThunderPhone megjelenik a csatlakozók könyvtárában, válassza ki. Ellenkező esetben válassza az Egyéni csatlakozó hozzáadása lehetőséget, nevezze el ThunderPhone néven, majd adja meg a következőt: https://api.thunderphone.com/v1/mcp.
Válassza a Csatlakozás lehetőséget, jelentkezzen be a ThunderPhone szolgáltatásba, válassza ki a szervezetet, majd hagyja jóvá az engedélyeket.
Egy csevegésben engedélyezze a ThunderPhone-t az eszközök menüjéből, majd kérje, amire szüksége van, például: „Listázd az ügynökeimet”.

A Claude minden eszköz első használata előtt jóváhagyást kér. A legtöbb ilyen kérdés kihagyásához nyissa meg a Testreszabás → Csatlakozók → ThunderPhone menüt, és állítsa a Csak olvasható eszközök beállítást mindig engedélyezettre. Ezek az eszközök csak információkat keresnek ki: ügynököket, hívásokat, átiratokat, egyenlegeket és dokumentációt. Hagyja jóváhagyáson az Írási/törlési eszközök beállítást, ha minden módosítást látni szeretne, mielőtt az megtörténik.

Az egyéni csatlakozókhoz fizetős Claude-csomag szükséges. Team és Enterprise csomagok esetén egy tulajdonosnak először a szervezet csatlakozóbeállításaiban kell hozzáadnia a csatlakozót, majd minden tagnak a saját ThunderPhone-fiókját kell csatlakoztatnia.

ChatGPT

Ha a ThunderPhone megjelenik a ChatGPT alkalmazáskönyvtárában, válassza ki, és csatlakoztassa.
Ellenkező esetben nyissa meg a Beállítások → Alkalmazások és csatlakozók → Speciális beállítások menüt, kapcsolja be a Fejlesztői módot, majd hozzon létre egy csatlakozót a https://api.thunderphone.com/v1/mcp URL-lel és OAuth-hitelesítéssel.
Jelentkezzen be a ThunderPhone szolgáltatásba, válassza ki a szervezetet, majd hagyja jóvá az engedélyeket. Adja hozzá a ThunderPhone-t egy csevegéshez az eszközök menüjéből.

Egy ügynök vagy telefonszám törlése, egy piszkozat elvetése, kampány indítása, valamint külső rendszerbe írni képes tesztkérés küldése mindkét alkalmazásban második megerősítést kér; lásd: Romboló műveletek megerősítése.

Claude Code

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

Codex

Adja hozzá ezt a ~/.codex/config.toml fájlhoz:

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

Cursor

Hozza létre a .cursor/mcp.json fájlt:

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

Claude Desktop

Adjon hozzá egy mcp-remote hidat a Claude Desktop konfigurációjához:

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

Hozza létre a .vscode/mcp.json fájlt, és adja meg a kulcsot a VS Code beviteli kérésén keresztül:

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

Eszközök

Minden eszköz MCP-jelöléseket tartalmaz. A táblázatokban az R csak olvashatót, a D destruktívat, az I idempotenset, az O pedig nyílt világú/hálózati interakciót jelent. A kötőjel azt jelenti, hogy nincs beállítva jelzés.

Kapcsolat

Eszköz	Fő argumentumok	Jelölések	Funkció
`get_connection_identity`	—	R, I	Ellenőrzi a hitelesítő adatot, és visszaadja a szervezetet, valamint a hitelesítő adat biztonságos metaadatait.

Ügynökök

Eszköz	Fő argumentumok	Jelölések	Működés
`list_agents`	—	R, I	Felsorolja az ügynököket.
`get_agent`	`agent_id`	R, I	Lekér egy ügynököt.
`create_agent`	ügynökkonfiguráció	—	Létrehoz egy ügynököt.
`update_agent`	`agent_id`, módosított mezők	D	Az ügynök piszkozatában előkészíti a mezőket, lecserélve a piszkozat korábbi értékeit. Megerősítési lépés nélkül fut: az éles ügynök változatlan marad a `deploy_agent` futtatásáig, a `discard_agent_draft` pedig visszaállítja a piszkozatot.
`deploy_agent`	`agent_id`, opcionális `if_updated_at`	D, I	Éles környezetbe helyezi a piszkozatot.
`discard_agent_draft`	`agent_id`, opcionális `if_updated_at`, a második kérésben `confirmation_token`	D, I	Elveti az előkészített módosításokat. Kétlépéses, lásd: Romboló műveletek megerősítése.
`duplicate_agent`	`agent_id`, opcionális `name`	—	Lemásol egy ügynököt a szervezeten belül.
`delete_agent`	`agent_id`, a második kérésben `confirmation_token`	D, I	Véglegesen töröl egy ügynököt. Kétlépéses.
`list_agent_versions`	`agent_id`	R, I	Felsorolja az éles konfigurációverziókat.

Telefonszámok és szolgáltatók

Eszköz	Fő argumentumok	Jelölések	Funkció
`list_phone_numbers`	—	R, I	Felsorolja a szervezet telefonszámait és az útválasztást.
`get_phone_number_limits`	—	R, I	Lekéri a kezelt telefonszámok használatát és korlátait.
`provision_phone_number`	opcionális `area_code`, `city`, `state`, `idempotency_key`	D, O	ThunderPhone által kezelt bejövő telefonszámot vásárol.
`list_voip_connections`	—	R, I	Felsorolja a csatlakoztatott ügyfél-szolgáltatókat.
`search_voip_numbers`	`connection_id`, `country`, `type`, opcionális `area_code`	R, I, O	Keres a szolgáltatói készletben.
`import_voip_numbers`	`connection_id`, `numbers`	D, O	Importálja a szolgáltatónál már birtokolt telefonszámokat.
`update_phone_number`	`phone_number_id`, útválasztási/címke/webhook mezők	D	Frissíti a telefonszám útválasztását, beleértve az ügynök hozzárendelését is.
`delete_phone_number`	`phone_number_id`, `confirm`, opcionális `release_at_provider`, a második kérésben `confirmation_token`	D, I, O	Felszabadít egy telefonszámot. Kétlépéses.

SMS

Eszköz	Fő argumentumok	Megjegyzések	Leírás
`send_sms`	`from_number`, `to`, `body`, `idempotency_key`	D, I, O	Egy egyszerű szöveges SMS-t küld egy csatlakoztatott Twilio- vagy Telnyx-számon keresztül.

Hívások

Eszköz	Fő argumentumok	Annotációk	Művelet
`list_calls`	opcionális szűrők, `limit`, `offset`	R, I	Felsorolja a hívásokat a REST híváselőzmény-szűrőivel.
`get_call`	`call_id`	R, I	Lekéri a hívás állapotát és metaadatait.
`get_call_transcript`	`call_id`, opcionális `live`	R, I	Lekéri a hívás átiratát.
`get_call_audio_url`	`call_id`, opcionális `download`	R, I, O	Visszaad egy aláírt hanganyag-URL-t; a hanganyagot soha nem streameli MCP-n keresztül.
`get_call_grade`	`call_id`	R, I	Lekéri a legfrissebb hívásértékelést.
`place_call`	`agent_id`, `from_number`, `to_number`	D, O	Egy nem idempotens kimenő hívást indít.
`export_calls`	hívásszűrők, `export_format`	R, I	A REST-végpont korlátjáig exportál JSON- vagy CSV-formátumban.

Tesztelés és ellenőrzés

Eszköz	Fő argumentumok	Megjegyzések	Funkció
`list_test_scenarios`	`agent_id`	R, I	Felsorolja a tesztforgatókönyveket.
`create_test_scenario`	`agent_id`, `title`, `scenario_prompt`, opcionális feltételek	—	Létrehoz egy forgatókönyvet.
`generate_test_scenarios`	`agent_id`, opcionális `count`, `include_edge_cases`, `locale`	O	Forgatókönyveket generál az ügynök promptja alapján.
`run_agent_tests`	`agent_id`, `channel`, `consent_to_charge`, opcionális kiválasztás/mátrix	D, O	Weben vagy telefonon keresztül futtatja a forgatókönyveket.
`get_test_run`	`agent_id`, `batch_id`	R, I	Lekéri a köteg állapotát és a forgatókönyvenkénti eredményeket.
`list_validation_runs`	`agent_id`	R, I	Felsorolja a legutóbbi piszkozat-érvényesítési futtatásokat.
`get_validation_status`	`agent_id`	R, I	Lekéri a legfrissebb érvényesítési állapotot és a piszkozat egyezését.

Tudás

Eszköz	Fő argumentumok	Jelölések	Funkció
`list_knowledge_bases`	—	R, I	Felsorolja a tudásbázisokat.
`create_knowledge_base`	`name`, opcionális `description`	—	Létrehoz egy tudásbázist.
`add_knowledge_document`	`knowledge_base_id`, `name`, `content`	—	Szöveget vagy Markdownt ad hozzá.
`import_knowledge_url`	`url`, opcionális `name`	O	Nyilvános oldalt helyez várólistára biztonságos betöltéshez.
`search_knowledge`	`knowledge_base_id`, `query`	R, I	Keres az éles visszakeresésben.

Integrációk, webhookok és távoli MCP-szerverek

Eszköz	Fő argumentumok	Jelölések	Leírás
`list_integrations`	—	R, I	Felsorolja a HTTP-függvényintegrációkat.
`create_integration`	`display_name`, függvény-`spec`, opcionális végpontmezők	—	Létrehoz egy HTTP-eszközt. Adja hozzá a hitelesítési fejléceket az irányítópulton.
`test_integration`	`url`, opcionális metódus/törzs/időtúllépés, `integration_id` `header_names` értékkel, `confirmation_token` a második kérésnél	D, O	Korlátozott, SSRF-védett tesztkérést küld. A mentett fejlécértékeket az integrációból tölti ki, és csak annak saját gazdagépére küldi el. A `POST` (az alapértelmezett), a `PUT`, a `PATCH` és a `DELETE` kétlépéses; a `GET` azonnal lefut.
`list_webhook_endpoints`	—	R, I	Felsorolja az aláírt webhook-végpontokat.
`list_webhook_deliveries`	opcionális `agent_id`, opcionális `endpoint_id`	R, I	Felsorolja a legutóbbi, hasznos adat nélküli webhook-kézbesítési eredményeket.
`create_webhook_endpoint`	`label`, `url`, opcionális események/állapot	O	Létrehoz egy aláírt webhook-végpontot.
`test_webhook_endpoint`	`endpoint_id`	O	Szintetikus eseményt küld normál kézbesítéssel.
`list_mcp_servers`	—	R, I	Felsorolja a hangalapú AI-ügynökök által hívható távoli szervereket.
`create_mcp_server`	`display_name`, `url`	O	Regisztrál és szinkronizál egy távoli szervert. A hitelesítési fejléceket igénylő szervereket az irányítópulton adhatja hozzá.
`sync_mcp_server_tools`	`server_id`	D, O	Frissíti egy távoli szerver eszközkatalógusát.

Kampányok

Eszköz	Fő argumentumok	Jelölések	Funkció
`list_campaigns`	—	R, I	Felsorolja a kimenő kampányokat.
`create_campaign`	kampánymezők	—	Létrehoz egy kampánypiszkozatot.
`add_campaign_contacts`	`campaign_id`, `contacts`	—	Legfeljebb 5 000 JSON-kapcsolatot ad hozzá.
`campaign_action`	`campaign_id`, `action`, opcionális `consent_to_charge`, `confirmation_token` a második kérésben	D, O	Futtatja a következők egyikét: `start`, `pause`, `resume` vagy `stop`. A `start` és a `resume` kétlépéses; a `pause` és a `stop` azonnal lefut.
`get_campaign_stats`	`campaign_id`	R, I	Lekéri a számlálókat és a legutóbbi eredményeket.

Hangok, számlázás és dokumentáció

Eszköz	Fő argumentumok	Jelölések	Funkció
`list_voices`	—	R, I	Felsorolja a hangokat és a támogatott nyelveket.
`preview_voice`	`voice`, `language`, `text`	O	Mintát generál, és aláírt URL-t ad vissza.
`list_voice_clones`	—	R, I	Felsorolja az egyéni hangklónokat.
`get_billing_summary`	—	R, I	Lekéri az egyenleget és a hiteles csomagárakat; fizetési módosítások nem érhetők el.
`search_docs`	`query`, opcionális `limit`	R, I, O	Keres a nyilvános dokumentációs indexben.
`get_doc_page`	`path`	R, I, O	Lekér egy nyilvános Markdown-dokumentációs oldalt.

Minden termékeszköz ugyanazokat a REST-kódútvonalakat használja, mint a nyilvános API. Ezért a REST-ellenőrzés, a szervezeti hatókör, a szerepkörök, a számlázási engedélyezés, a kvóták, a TCPA-megerősítés, a szolgáltatói biztonság és a naplózási működés változatlanul érvényes.

Visszafordíthatatlan műveletek megerősítése

A D jelöléssel ellátott eszközök módosítanak vagy eltávolítanak valamit, illetve valódi személyek hívását kezdeményezik. A vissza nem vonható műveletekhez két kérés szükséges. Az első kérés nem módosít semmit, és a következőt adja vissza:

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

Az asszisztens megmutatja a felhasználónak, mire van hatással a művelet, és megerősítést kér. Ezután megismétli a kérést ugyanazokkal az argumentumokkal, kiegészítve a confirmation_token értékével. Egy token 10 percig érvényes, és egy szervezetre, egy eszközre, valamint egy pontos argumentumkészletre vonatkozik, ezért három ügynök törléséhez három megerősítés szükséges. A campaign_action a pause vagy stop értékkel kihagyja ezt a lépést, így egy futó kampány mindig azonnal leállítható, ahogyan a test_integration is GET használatakor. Egyes D jelölésű eszközök egyetlen kérésben futnak le, mert a D a hatásukat jelöli, nem pedig szerveroldali megerősítést: az update_agent lecseréli a piszkozat tartalmát (a discard_agent_draft visszaállítja azt), a deploy_agent lecseréli az éles konfigurációt, az update_phone_number átirányítja az éles hívásokat, a sync_mcp_server_tools lecseréli egy távoli szerver eszközkatalógusát, az import_voip_numbers átirányítja a számokat az Ön szolgáltatójához, a run_agent_tests kreditet használhat fel, a send_sms és a place_call valódi személyt ér el (a place_call megtartja saját hozzájárulási megerősítését), a provision_phone_number pedig telefonszámot vásárol. Az Ön MCP-kliense ettől függetlenül kérheti, hogy hagyja jóvá ezeket.

Kezdő promptok

A prompts/list öt újrahasználható munkafolyamatot kínál:

create_inbound_receptionist
run_agent_tests
buy_and_attach_number
review_low_grade_calls
add_url_to_agent_knowledge

Használja a prompts/get műveletet a felsorolt promptnévvel és a deklarált argumentumaival, hogy futtatásra kész felhasználói üzenetet kapjon.

Erőforrások

A resources/list nyilvános, gyorsítótárazott hivatkozásokat tesz elérhetővé:

URI	Tartalom
`thunderphone://docs/llms.txt`	Nyilvános dokumentációs index.
`thunderphone://docs/quickstart`	Gyorsindítási Markdown.
`thunderphone://pricing`	Aktuális nyilvános árazási Markdown.

Olvasson be egyet a resources/read művelettel. A nyilvános lekérések rövid időtúllépést, 2 MiB-os korlátot és tízperces folyamaton belüli gyorsítótárat használnak.

Protokoll és hibák

A szerver a 2025-06-18 és 2025-03-26 protokollverziókat támogatja; visszaad egy támogatott kliensverziót, egyébként pedig a 2025-06-18 verziót választja. Megvalósítja az initialize, ping, eszközök, promptok, erőforrások és értesítések funkcióit. Az értesítések 202 Accepted választ adnak vissza. Ez az állapotmentes szerver nem tesz elérhetővé SSE-figyelőt vagy munkamenettörlést, ezért a GET és DELETE kérések 405 Method Not Allowed választ adnak vissza Allow: POST fejlécértékkel.

Az eszközhibák továbbra is sikeres JSON-RPC-válaszok maradnak isError: true értékkel. A szövegük egy rövid mondatot tartalmaz, amelyet egy JSON-blokk követ:

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

A megkülönböztető outbound_tcpa_confirmation_required: előtag megmarad a place_call esetében. Az ismeretlen JSON-RPC-metódusok -32601 értéket adnak vissza HTTP 200 válaszban. A JSON-RPC-kötegeket az MCP 2025-06-18 nem támogatja, és tiszta -32600 érvénytelen kérés hibát adnak vissza.