---
title: "Tumia ThunderPhone kama seva ya MCP"
description: "Jenga, jaribu, thibitisha, na endesha ejenti za sauti za ThunderPhone ukitumia Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code, au mteja mwingine wa Streamable HTTP MCP."
---

ThunderPhone hutoa seva ya Streamable HTTP Model Context Protocol katika:

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

Hii ni mwelekeo kinyume na [kuunganisha seva ya MCP ya mbali kwenye ejenti ya sauti](/sw/guides/mcp-servers):

| Mwelekeo | Matokeo |
| --- | --- |
| Seva ya MCP ya mbali → ejenti ya ThunderPhone | Ejenti ya sauti inaweza kuita zana za seva ya mbali. |
| ThunderPhone → mteja wako wa MCP | Ejenti wako wa kuandika msimbo anaweza kuunda, kujaribu, na kuendesha ThunderPhone. |

## Thibitisha utambulisho

Tumia [OAuth](/sw/guides/oauth) kwa chaguo-msingi kwa wateja wa saraka: ingia, chagua shirika, na idhinisha ruhusa zilizoombwa. Batilisha ufikiaji chini ya **Shirika → Vifunguo vya API → Programu zilizoidhinishwa**.

Kwa wateja waliowekwa na ufunguo wa API, unda ufunguo wa `sk_live_` chini ya **Shirika → Vifunguo** na uupe mteja wako wa MCP kama `THUNDERPHONE_API_KEY`. Ufunguo huu umefungwa kwa shirika moja; kitambulisho kinachomilikiwa na shirika lingine hutenda kana kwamba hakipatikani.

<Warning>
  Ufunguo wa `sk_live_` unaweza kusoma data ya shirika na kutekeleza vitendo vya uzalishaji kama kusambaza ejenti, kupiga simu, kununua namba, kuanzisha kampeni, na kufuta rasilimali. Usiuweke kwenye msimbo wa kivinjari, hazina, picha za skrini, na kumbukumbu za mazungumzo. Tumia hifadhi ya siri ya mteja wako au usaidizi wa mazingira, na batilisha ufunguo uliofichuliwa mara moja.
</Warning>

## Njia mbadala za CLI na stdio

[ThunderPhone CLI](/sw/guides/cli) inaweza kuandika usanidi wa mteja huku ikihifadhi
seva zisizohusiana:

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

Baada ya usakinishaji wa kimataifa wa `@thunderphone/mcp`, tumia `thunderphone-mcp setup` ukiwa na
chaguo zilezile. Usanidi unaauni Claude Code, Codex, Cursor, VS Code, Gemini, Claude
Desktop na Windsurf. HTTP ya moja kwa moja inapendekezwa; Desktop hutumia stdio.

Kwa mteja wowote unaoweza kutumia stdio, sanidi `command: "npx"` kwa
`args: ["-y", "@thunderphone/mcp"]`. Kifuniko hutumia `THUNDERPHONE_API_KEY` kwanza,
kisha stakabadhi kutoka `thunderphone login`, ikihuisha tokeni zilizoisha muda wake, kisha
OAuth kupitia `mcp-remote`. Kuingia kwa kifaa na OAuth kunahitaji uwezeshaji unaolingana wa OAuth wa API.
Njia ya ufunguo wa API haihitaji hivyo. Usanidi wa HTTP wa moja kwa moja hausomi
hifadhi ya stakabadhi za CLI; tumia kifuniko cha stdio ili kutumia tena kuingia kwa kifaa.

Hizi ni njia mbadala za usanidi wa mikono wa mteja hapa chini.

## Usanidi wa mteja

Claude na ChatGPT huingia kwa kutumia [OAuth](/sw/guides/oauth); hakuna ufunguo wa API unaohitajika. Ikiwa bado huna akaunti ya ThunderPhone, chagua **Unda akaunti** kwenye ukurasa wa kuingia, kisha utarudi kwenye skrini ya idhini baada ya kuthibitisha barua pepe yako.

### Claude (wavuti, kompyuta ya mezani, na simu)

1. Fungua **Mipangilio → Viunganishi**. Ikiwa ThunderPhone inaonekana kwenye saraka ya viunganishi, ichague. Vinginevyo chagua **Ongeza kiunganishi maalum**, kipe jina `ThunderPhone`, na uweke `https://api.thunderphone.com/v1/mcp`.
2. Chagua **Unganisha**, ingia kwenye ThunderPhone, chagua shirika, na idhinisha ruhusa.
3. Kwenye mazungumzo, wezesha ThunderPhone kutoka kwenye menyu ya zana na uombe unachohitaji, kwa mfano "Orodhesha ejenti zangu".

Viunganishi maalum vinahitaji mpango wa Claude wa kulipia. Kwenye mipango ya Team na Enterprise, mmiliki huongeza kiunganishi kwanza chini ya mipangilio ya viunganishi vya shirika, kisha kila mwanachama huunganisha akaunti yake ya ThunderPhone.

### ChatGPT

1. Ikiwa ThunderPhone inaonekana kwenye saraka ya programu za ChatGPT, ichague na uiunganishe.
2. Vinginevyo fungua **Mipangilio → Programu na Viunganishi → Mipangilio ya kina**, washa **Hali ya msanidi**, na uunde kiunganishi chenye URL `https://api.thunderphone.com/v1/mcp` na uthibitishaji wa OAuth.
3. Ingia kwenye ThunderPhone, chagua shirika, na idhinisha ruhusa. Ongeza ThunderPhone kwenye mazungumzo kutoka kwenye menyu ya zana.

Kufuta ejenti au nambari ya simu, kutupa rasimu, na kuzindua kampeni huhitaji uthibitisho wa pili katika programu yoyote; tazama [Kuthibitisha vitendo vya kuharibu](#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

Ongeza hii kwenye `~/.codex/config.toml`:

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

### Cursor

Unda `.cursor/mcp.json`:

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

### Claude Desktop

Ongeza daraja la `mcp-remote` kwenye usanidi wa Claude Desktop:

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

Unda `.vscode/mcp.json` na uweke ufunguo kupitia kidokezo cha ingizo cha VS Code:

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

## Zana

Kila zana ina vidokezo vya MCP. Katika majedwali, **R** inamaanisha kusoma pekee, **D** uharibifu, **I** isiyobadilisha matokeo ikirudiwa, na **O** mwingiliano wa mtandao/ulimwengu wazi. Kistari kinamaanisha hakuna kidokezo kilichowekwa.

### Ejenti

| Zana | Hoja kuu | Vidokezo | Inachofanya |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | Huorodhesha ejenti. |
| `get_agent` | `agent_id` | R, I | Hupata ejenti mmoja. |
| `create_agent` | usanidi wa ejenti | — | Huunda ejenti. |
| `update_agent` | `agent_id`, sehemu zilizobadilishwa | — | Huandaa sehemu katika rasimu ya ejenti. |
| `deploy_agent` | `agent_id`, `if_updated_at` ya hiari | I | Hupandisha rasimu hadi uzalishaji. |
| `discard_agent_draft` | `agent_id`, `if_updated_at` ya hiari, `confirmation_token` kwenye ombi la pili | D, I | Hutupa mabadiliko yaliyoandaliwa. Hatua mbili, angalia [Kuthibitisha vitendo vya uharibifu](#confirming-destructive-actions). |
| `duplicate_agent` | `agent_id`, `name` ya hiari | — | Hunakili ejenti ndani ya shirika. |
| `delete_agent` | `agent_id`, `confirmation_token` kwenye ombi la pili | D, I | Hufuta ejenti kabisa. Hatua mbili. |
| `list_agent_versions` | `agent_id` | R, I | Huorodhesha matoleo ya usanidi uliotumwa. |

### Nambari za simu na watoa huduma

| Zana | Hoja kuu | Vidokezo | Inachofanya |
| --- | --- | --- | --- |
| `list_phone_numbers` | — | R, I | Huorodhesha nambari za shirika na uelekezaji. |
| `get_phone_number_limits` | — | R, I | Hupata matumizi na vikomo vya nambari zinazosimamiwa. |
| `provision_phone_number` | `area_code`, `city`, `state`, `idempotency_key` za hiari | O | Hununuwa nambari ya kupokea simu inayosimamiwa na ThunderPhone. |
| `list_voip_connections` | — | R, I | Huorodhesha watoa huduma wa wateja waliounganishwa. |
| `search_voip_numbers` | `connection_id`, `country`, `type`, `area_code` ya hiari | R, I, O | Hutafuta orodha ya nambari za mtoa huduma. |
| `import_voip_numbers` | `connection_id`, `numbers` | O | Huagiza nambari ambazo tayari zinamilikiwa na mtoa huduma. |
| `update_phone_number` | `phone_number_id`, sehemu za uelekezaji/lebo/webhook | — | Husasisha uelekezaji wa nambari, ikijumuisha ugawaji wa ejenti. |
| `delete_phone_number` | `phone_number_id`, `confirm`, `release_at_provider` ya hiari, `confirmation_token` kwenye ombi la pili | D, I, O | Hutoa nambari. Hatua mbili. |

### Simu

| Zana | Hoja kuu | Vidokezo | Inachofanya |
| --- | --- | --- | --- |
| `list_calls` | vichujio vya hiari, `limit`, `offset` | R, I | Huorodhesha simu kwa vichujio vya historia ya simu vya REST. |
| `get_call` | `call_id` | R, I | Hupata hali na metadata ya simu. |
| `get_call_transcript` | `call_id`, `live` ya hiari | R, I | Hupata nakala ya mazungumzo ya simu. |
| `get_call_audio_url` | `call_id`, `download` ya hiari | R, I, O | Hurejesha URL ya sauti iliyotiwa saini; haitiririshi kamwe sauti kupitia MCP. |
| `get_call_grade` | `call_id` | R, I | Hupata alama ya hivi karibuni ya simu. |
| `place_call` | `agent_id`, `from_number`, `to_number` | O | Hupiga simu moja ya kutoka isiyo na idempotensi. |
| `export_calls` | vichujio vya simu, `export_format` | R, I | Husafirisha hadi kikomo cha endpoint ya REST kama JSON au CSV. |

### Upimaji na uthibitishaji

| Zana | Hoja kuu | Vidokezo | Inachofanya |
| --- | --- | --- | --- |
| `list_test_scenarios` | `agent_id` | R, I | Huorodhesha hali za majaribio. |
| `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, masharti ya hiari | — | Huunda hali. |
| `generate_test_scenarios` | `agent_id`, `count`, `include_edge_cases`, `locale` za hiari | O | Huzalisha hali kutoka kwenye prompt ya ejenti. |
| `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, uteuzi/matrix ya hiari | O | Hutekeleza hali kupitia wavuti au simu. |
| `get_test_run` | `agent_id`, `batch_id` | R, I | Hupata hali ya kundi na matokeo kwa kila hali. |
| `list_validation_runs` | `agent_id` | R, I | Huorodhesha utekelezaji wa hivi karibuni wa uthibitishaji wa rasimu. |
| `get_validation_status` | `agent_id` | R, I | Hupata hali ya hivi karibuni ya uthibitishaji na ulinganifu wa rasimu. |

### Maarifa

| Zana | Hoja kuu | Vidokezo | Inachofanya |
| --- | --- | --- | --- |
| `list_knowledge_bases` | — | R, I | Huorodhesha misingi ya maarifa. |
| `create_knowledge_base` | `name`, `description` ya hiari | — | Huunda msingi wa maarifa. |
| `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | Huongeza maandishi au Markdown. |
| `import_knowledge_url` | `url`, `name` ya hiari | O | Hupanga ukurasa wa umma kwa uingizaji salama. |
| `search_knowledge` | `knowledge_base_id`, `query` | R, I | Hutafuta kupitia urejeshaji wa uzalishaji. |

### Miunganisho, webhook, na seva za MCP za mbali

| Zana | Hoja kuu | Vidokezo | Inachofanya |
| --- | --- | --- | --- |
| `list_integrations` | — | R, I | Huorodhesha miunganisho ya vitendakazi vya HTTP. |
| `create_integration` | `display_name`, `spec` ya kitendakazi, sehemu za endpoint za hiari | — | Huunda zana ya HTTP. |
| `test_integration` | `url`, method/headers/body/timeout za hiari | O | Hutuma ombi la majaribio lenye mipaka na lililolindwa dhidi ya SSRF. |
| `list_webhook_endpoints` | — | R, I | Huorodhesha endpoint za webhook zilizotiwa saini. |
| `create_webhook_endpoint` | `label`, `url`, events/status za hiari | O | Huunda endpoint ya webhook iliyotiwa saini. |
| `test_webhook_endpoint` | `endpoint_id` | O | Hutuma tukio bandia kupitia uwasilishaji wa kawaida. |
| `list_mcp_servers` | — | R, I | Huorodhesha seva za mbali zinazoweza kuitwa na ejenti za sauti. |
| `create_mcp_server` | `display_name`, `url`, headers za hiari | O | Husajili na kusawazisha seva ya mbali. |
| `sync_mcp_server_tools` | `server_id` | O | Husasisha katalogi ya zana ya seva ya mbali. |

### Kampeni

| Zana | Hoja kuu | Vidokezo | Inachofanya |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | Huorodhesha kampeni za kupiga simu za kutoka. |
| `create_campaign` | sehemu za kampeni | — | Huunda rasimu ya kampeni. |
| `add_campaign_contacts` | `campaign_id`, `contacts` | — | Huongeza hadi mawasiliano 5,000 ya JSON. |
| `campaign_action` | `campaign_id`, `action`, `consent_to_charge` ya hiari, `confirmation_token` kwenye ombi la pili | D, O | Hutekeleza `start`, `pause`, `resume`, au `stop`. `start` na `resume` ni za hatua mbili; `pause` na `stop` hutekelezwa mara moja. |
| `get_campaign_stats` | `campaign_id` | R, I | Hupata vihesabu na matokeo ya hivi karibuni. |

### Sauti, bili, uagizaji, na nyaraka

| Zana | Hoja kuu | Vidokezo | Inachofanya |
| --- | --- | --- | --- |
| `list_voices` | — | R, I | Huorodhesha sauti na lugha zinazotumika. |
| `preview_voice` | `voice`, `language`, `text` | O | Huzalisha sampuli na kurejesha URL iliyotiwa saini. |
| `list_voice_clones` | — | R, I | Huorodhesha nakala maalum za sauti. |
| `get_billing_summary` | — | R, I | Hupata salio na bei rasmi za viwango; hakuna mabadiliko ya malipo yanayotolewa. |
| `create_agent_import` | `vendor`, `vendor_key` | O | Huanza uagizaji uliosimbwa wa Vapi, Retell, ElevenLabs, au Bland. |
| `get_agent_import` | `public_id` | R, I | Hupata tofauti ya uagizaji uliopendekezwa. |
| `commit_agent_import` | `public_id` | — | Huthibitisha ejenti zilizochaguliwa kutoka kwenye mpango uliokaguliwa. |
| `search_docs` | `query`, `limit` ya hiari | R, I, O | Hutafuta faharasa ya nyaraka za umma. |
| `get_doc_page` | `path` | R, I, O | Huchukua ukurasa mmoja wa umma wa nyaraka za Markdown. |

Zana zote za bidhaa hutumia njia zilezile za msimbo wa REST kama API ya umma. Kwa hiyo, uthibitishaji wa REST, upeo wa shirika, majukumu, idhini ya bili, viwango vya matumizi, uthibitisho wa TCPA, usalama wa mtoa huduma, na mwenendo wa ukaguzi hutumika bila mabadiliko.

## Kuthibitisha vitendo visivyoweza kutenduliwa

Zana zilizo na alama D hubadilisha au kuondoa kitu kisichoweza kurejeshwa, au huanza kupiga simu watu halisi. Zinahitaji maombi mawili. Ombi la kwanza halibadilishi chochote na hurejesha:

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

Ejenti humwonyesha mtumiaji kinachoathiriwa na kuomba uthibitisho wa ndiyo. Kisha hurudia ombi kwa hoja zilezile pamoja na `confirmation_token`. Tokeni ni halali kwa dakika 10 na inahusu shirika moja, zana moja, na seti moja mahususi ya hoja, hivyo kufuta ejenti watatu kunahitaji uthibitisho tatu. `campaign_action` yenye `pause` au `stop` huruka hatua hii ili kampeni inayoendelea iweze kusimamishwa mara moja kila wakati.

## Prompt za kuanzia

`prompts/list` hutangaza mitiririko sita ya kazi inayoweza kutumika tena:

- `create_inbound_receptionist`
- `run_agent_tests`
- `import_vapi_assistants`
- `buy_and_attach_number`
- `review_low_grade_calls`
- `add_url_to_agent_knowledge`

Tumia `prompts/get` kwa jina la prompt lililoorodheshwa na hoja zake zilizotangazwa ili kupokea ujumbe wa mtumiaji ulio tayari kuendeshwa.

## Rasilimali

`resources/list` hufichua marejeleo ya umma yaliyohifadhiwa kwenye cache:

| URI | Maudhui |
| --- | --- |
| `thunderphone://docs/llms.txt` | Faharasa ya nyaraka za umma. |
| `thunderphone://docs/quickstart` | Markdown ya kuanza haraka. |
| `thunderphone://pricing` | Markdown ya bei za sasa za umma. |

Soma moja ukitumia `resources/read`. Upataji wa umma hutumia muda mfupi wa kuisha, kikomo cha MiB 2, na cache ya ndani ya mchakato ya dakika kumi.

## Itifaki na hitilafu

Seva inasaidia matoleo ya itifaki `2025-06-18` na `2025-03-26`; hurudisha toleo la mteja linalosaidiwa na vinginevyo huchagua `2025-06-18`. Inatekeleza `initialize`, `ping`, zana, prompt, rasilimali na arifa. Arifa hurejesha `202 Accepted`. Seva hii isiyo na hali haifichui msikilizaji wa SSE au ufutaji wa kipindi, hivyo `GET` na `DELETE` hurejesha `405 Method Not Allowed` pamoja na `Allow: POST`.

Hitilafu za zana hubaki kuwa majibu yaliyofanikiwa ya JSON-RPC yenye `isError: true`. Maandishi yake yana sentensi fupi ikifuatiwa na kizuizi cha JSON:

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

Kiambishi awali tofauti cha `outbound_tcpa_confirmation_required:` huhifadhiwa kwa `place_call`. Mbinu zisizojulikana za JSON-RPC hurejesha `-32601` katika jibu la HTTP `200`. Makundi ya JSON-RPC hayaauniwi na MCP `2025-06-18` na hurejesha hitilafu safi ya ombi batili `-32600`.