Open in

השתמשו ב-ThunderPhone כשרת MCP

בנו, בדקו, אמתו והפעילו סוכני קול של ThunderPhone מתוך Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code או לקוח MCP אחר מסוג Streamable HTTP.

ThunderPhone חושפת שרת MCP באמצעות HTTP ניתן להזרמה בכתובת:

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

זהו הכיוון ההפוך מ-חיבור שרת MCP מרוחק לסוכן קולי:

כיוון	תוצאה
שרת MCP מרוחק → סוכן ThunderPhone	סוכן קולי יכול להפעיל את הכלים של השרת המרוחק.
ThunderPhone → לקוח MCP שלכם	סוכן התכנות שלכם יכול לבנות, לבדוק ולהפעיל את ThunderPhone.

אימות

השתמשו ב-OAuth כברירת מחדל עבור לקוחות ספרייה: התחברו, בחרו ארגון ואשרו את ההרשאות המבוקשות. בטלו גישה תחת ארגון → מפתחות API → אפליקציות מורשות.

עבור לקוחות שהוגדרו עם מפתח API, צרו מפתח sk_live_ תחת ארגון → מפתחות והעבירו אותו ללקוח MCP שלכם כ-THUNDERPHONE_API_KEY. המפתח מקושר לארגון אחד; מזהה השייך לארגון אחר מתנהג כאילו לא נמצא.

חלופות CLI ו-stdio

ה-CLI של ThunderPhone יכול לכתוב את תצורת הלקוח תוך שמירה על שרתים שאינם קשורים:

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

לאחר התקנה כללית של @thunderphone/mcp, השתמשו ב-thunderphone-mcp setup עם אותן אפשרויות. ההגדרה תומכת ב-Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop ו-Windsurf. עדיף להשתמש ב-HTTP ישיר; גרסת שולחן העבודה משתמשת ב-stdio.

לכל לקוח התומך ב-stdio, הגדירו את command: "npx" עם args: ["-y", "@thunderphone/mcp"]. המעטפת משתמשת תחילה ב-THUNDERPHONE_API_KEY, ולאחר מכן בפרטי הכניסה מ-thunderphone login, מרעננת אסימונים שפג תוקפם, ולאחר מכן ב-OAuth דרך mcp-remote. כניסה ממכשיר ו-OAuth דורשים את ההשקה המתאימה של OAuth ב-API. נתיב מפתח ה-API אינו דורש זאת. תצורות HTTP ישירות אינן קוראות את מאגר פרטי הכניסה של ה-CLI; השתמשו במעטפת stdio כדי לעשות שימוש חוזר בכניסה ממכשיר.

אלו חלופות לתצורות הלקוח הידניות שלהלן.

תצורת לקוח

Claude ו-ChatGPT מאפשרים לכם להתחבר באמצעות OAuth; אין צורך במפתח API. אם עדיין אין לכם חשבון ThunderPhone, בחרו יצירת חשבון בדף ההתחברות, ולאחר אימות כתובת האימייל תחזרו למסך האישור.

Claude (אינטרנט, שולחן עבודה ונייד)

פתחו את התאמה אישית → מחברים (הגדרות → מחברים בגרסאות ישנות יותר). אם ThunderPhone מופיע בספריית המחברים, בחרו בו. אחרת, בחרו הוספת מחבר מותאם אישית, תנו לו את השם ThunderPhone, והזינו https://api.thunderphone.com/v1/mcp.
בחרו התחברות, התחברו ל-ThunderPhone, בחרו את הארגון ואשרו את ההרשאות.
בשיחה, הפעילו את ThunderPhone מתפריט הכלים ובקשו את מה שאתם צריכים, לדוגמה "הצג את הסוכנים שלי".

Claude מבקש אישור לפני השימוש הראשון בכל כלי. כדי לדלג על רוב הבקשות האלה, פתחו את התאמה אישית → מחברים → ThunderPhone והגדירו את כלים לקריאה בלבד כ-לאפשר תמיד. כלים אלה מבצעים רק חיפושים: סוכנים, שיחות, תמלילים, יתרות ותיעוד. השאירו את כלי כתיבה/מחיקה במצב אישור אם אתם רוצים לראות כל שינוי לפני שהוא מתבצע.

מחברים מותאמים אישית דורשים תוכנית Claude בתשלום. בתוכניות Team ו-Enterprise, בעלים מוסיף תחילה את המחבר בהגדרות המחברים של הארגון, ולאחר מכן כל חבר מחבר את חשבון ThunderPhone שלו.

ChatGPT

אם ThunderPhone מופיע בספריית האפליקציות של ChatGPT, בחרו בו והתחברו.
אחרת, פתחו את הגדרות → אפליקציות ומחברים → הגדרות מתקדמות, הפעילו את מצב מפתח, וצרו מחבר עם כתובת ה-URL https://api.thunderphone.com/v1/mcp ואימות OAuth.
התחברו ל-ThunderPhone, בחרו את הארגון ואשרו את ההרשאות. הוסיפו את ThunderPhone לשיחה מתפריט הכלים.

מחיקת סוכן או מספר טלפון, ביטול טיוטה, הפעלת קמפיין ושליחת בקשת בדיקה שיכולה לכתוב למערכת חיצונית דורשים אישור נוסף בכל אחת מהאפליקציות; ראו אישור פעולות הרסניות.

Claude Code

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

Codex

הוסיפו את זה אל ~/.codex/config.toml:

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

Cursor

צרו את .cursor/mcp.json:

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

Claude Desktop

הוסיפו גשר mcp-remote לתצורת Claude Desktop:

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

צרו את .vscode/mcp.json והזינו את המפתח באמצעות בקשת הקלט של VS Code:

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

כלים

כל כלי כולל הערות MCP. בטבלאות, R מציין קריאה בלבד, D פעולה הרסנית, I פעולה אידמפוטנטית, ו-O אינטראקציה עם העולם החיצון/הרשת. מקף מציין שלא הוגדר רמז.

חיבור

כלי	ארגומנטים עיקריים	הערות	מה הוא עושה
`get_connection_identity`	—	R, I	מאמת את פרטי ההזדהות ומחזיר את הארגון ואת המטא-נתונים הבטוחים של פרטי ההזדהות.

סוכנים

כלי	ארגומנטים עיקריים	הערות	מה הוא עושה
`list_agents`	—	R, I	מציג רשימת סוכנים.
`get_agent`	`agent_id`	R, I	מקבל סוכן אחד.
`create_agent`	תצורת סוכן	—	יוצר סוכן.
`update_agent`	`agent_id`, שדות שהשתנו	D	מכין שדות בטיוטת הסוכן, ומחליף את מה שהיה בטיוטה. פועל ללא שלב אישור: הסוכן שפורסם אינו משתנה עד להפעלת `deploy_agent`, ו-`discard_agent_draft` מחזיר את הטיוטה למצבה הקודם.
`deploy_agent`	`agent_id`, `if_updated_at` אופציונלי	D, I	מקדם את הטיוטה לייצור.
`discard_agent_draft`	`agent_id`, `if_updated_at` אופציונלי, `confirmation_token` בבקשה השנייה	D, I	מבטל שינויים שהוכנו. תהליך דו-שלבי, ראו אישור פעולות הרסניות.
`duplicate_agent`	`agent_id`, `name` אופציונלי	—	מעתיק סוכן בתוך הארגון.
`delete_agent`	`agent_id`, `confirmation_token` בבקשה השנייה	D, I	מוחק סוכן לצמיתות. תהליך דו-שלבי.
`list_agent_versions`	`agent_id`	R, I	מציג רשימת גרסאות תצורה שפורסמו.

מספרי טלפון וספקים

כלי	ארגומנטים עיקריים	הערות	מה הוא עושה
`list_phone_numbers`	—	R, I	מציג מספרי ארגון וניתוב.
`get_phone_number_limits`	—	R, I	מחזיר שימוש ומגבלות של מספרים מנוהלים.
`provision_phone_number`	אופציונליים: `area_code`, `city`, `state`, `idempotency_key`	D, O	רוכש מספר נכנס המנוהל על ידי ThunderPhone.
`list_voip_connections`	—	R, I	מציג ספקים מחוברים של לקוחות.
`search_voip_numbers`	`connection_id`, `country`, `type`, אופציונלי: `area_code`	R, I, O	מחפש במלאי הספק.
`import_voip_numbers`	`connection_id`, `numbers`	D, O	מייבא מספרים שכבר בבעלותכם אצל הספק.
`update_phone_number`	`phone_number_id`, שדות ניתוב/תווית/webhook	D	מעדכן את ניתוב המספר, כולל הקצאת סוכן.
`delete_phone_number`	`phone_number_id`, `confirm`, אופציונלי: `release_at_provider`, `confirmation_token` בבקשה השנייה	D, I, O	משחרר מספר. תהליך דו-שלבי.

SMS

כלי	ארגומנטים עיקריים	הערות	מה הוא עושה
`send_sms`	`from_number`, `to`, `body`, `idempotency_key`	D, I, O	שולח הודעת SMS אחת בטקסט פשוט דרך מספר Twilio או Telnyx מחובר.

שיחות

כלי	ארגומנטים עיקריים	הערות	מה הוא עושה
`list_calls`	מסננים אופציונליים, `limit`, `offset`	R, I	מציג רשימת שיחות באמצעות מסנני היסטוריית השיחות של REST.
`get_call`	`call_id`	R, I	מקבל את סטטוס השיחה והמטא-נתונים שלה.
`get_call_transcript`	`call_id`, `live` אופציונלי	R, I	מקבל את תמלול השיחה.
`get_call_audio_url`	`call_id`, `download` אופציונלי	R, I, O	מחזיר כתובת URL חתומה לאודיו; לעולם אינו מזרים אודיו דרך MCP.
`get_call_grade`	`call_id`	R, I	מקבל את דירוג השיחה העדכני ביותר.
`place_call`	`agent_id`, `from_number`, `to_number`	D, O	מבצע שיחה יוצאת אחת שאינה אידמפוטנטית.
`export_calls`	מסנני שיחות, `export_format`	R, I	מייצא עד למגבלה של נקודת הקצה REST בפורמט JSON או CSV.

בדיקות ואימות

כלי	ארגומנטים עיקריים	הערות	מה הוא עושה
`list_test_scenarios`	`agent_id`	R, I	מציג תרחישי בדיקה.
`create_test_scenario`	`agent_id`, `title`, `scenario_prompt`, תנאים אופציונליים	—	יוצר תרחיש.
`generate_test_scenarios`	`agent_id`, `count` אופציונלי, `include_edge_cases`, `locale`	O	יוצר תרחישים מתוך הנחיית הסוכן.
`run_agent_tests`	`agent_id`, `channel`, `consent_to_charge`, בחירה/מערך אופציונליים	D, O	מפעיל תרחישים דרך האינטרנט או הטלפוניה.
`get_test_run`	`agent_id`, `batch_id`	R, I	מחזיר את מצב האצווה ואת התוצאות לכל תרחיש.
`list_validation_runs`	`agent_id`	R, I	מציג הרצות אימות אחרונות של טיוטות.
`get_validation_status`	`agent_id`	R, I	מחזיר את מצב האימות העדכני ביותר ואת ההתאמה לטיוטה.

ידע

כלי	ארגומנטים עיקריים	הערות	מה הוא עושה
`list_knowledge_bases`	—	R, I	מציג מאגרי ידע.
`create_knowledge_base`	`name`, `description` אופציונלי	—	יוצר מאגר ידע.
`add_knowledge_document`	`knowledge_base_id`, `name`, `content`	—	מוסיף טקסט או Markdown.
`import_knowledge_url`	`url`, `name` אופציונלי	O	מכניס דף ציבורי לתור לצורך קליטה בטוחה.
`search_knowledge`	`knowledge_base_id`, `query`	R, I	מחפש באמצעות אחזור בייצור.

אינטגרציות, webhooks ושרתי MCP מרוחקים

כלי	ארגומנטים עיקריים	הערות	מה הוא עושה
`list_integrations`	—	R, I	מציג אינטגרציות של פונקציות HTTP.
`create_integration`	`display_name`, ‏`spec` של פונקציה, שדות אופציונליים של נקודת קצה	—	יוצר כלי HTTP. הוסיפו כותרות אימות בלוח הבקרה.
`test_integration`	`url`, שיטה/גוף/זמן קצוב אופציונליים, `integration_id` עם `header_names`, ‏`confirmation_token` בבקשה השנייה	D, O	שולח בקשת בדיקה מוגבלת המוגנת מפני SSRF. ערכי כותרות שמורים ממולאים מהאינטגרציה ונשלחים רק למארח שלה. `POST` (ברירת המחדל), `PUT`, `PATCH` ו-`DELETE` מתבצעים בשני שלבים; `GET` מופעל מיד.
`list_webhook_endpoints`	—	R, I	מציג נקודות קצה חתומות של וובהוקים.
`list_webhook_deliveries`	`agent_id` אופציונלי, `endpoint_id` אופציונלי	R, I	מציג תוצאות מסירה אחרונות של וובהוקים ללא מטענים.
`create_webhook_endpoint`	`label`, `url`, אירועים/סטטוס אופציונליים	O	יוצר נקודת קצה חתומה של וובהוק.
`test_webhook_endpoint`	`endpoint_id`	O	שולח אירוע סינתטי באמצעות המסירה הרגילה.
`list_mcp_servers`	—	R, I	מציג שרתים מרוחקים שסוכנים קוליים יכולים לקרוא להם.
`create_mcp_server`	`display_name`, `url`	O	רושם ומסנכרן שרת מרוחק. שרתים הדורשים כותרות אימות מתווספים בלוח הבקרה.
`sync_mcp_server_tools`	`server_id`	D, O	מרענן את קטלוג הכלים של שרת מרוחק.

קמפיינים

כלי	ארגומנטים עיקריים	הערות	מה הוא עושה
`list_campaigns`	—	R, I	מציג קמפיינים יוצאים.
`create_campaign`	שדות קמפיין	—	יוצר קמפיין טיוטה.
`add_campaign_contacts`	`campaign_id`, `contacts`	—	מוסיף עד 5,000 אנשי קשר בפורמט JSON.
`campaign_action`	`campaign_id`, `action`, `consent_to_charge` אופציונלי, `confirmation_token` בבקשה השנייה	D, O	מפעיל את `start`, `pause`, `resume` או `stop`. הפעולות `start` ו-`resume` הן בשני שלבים; הפעולות `pause` ו-`stop` פועלות מיידית.
`get_campaign_stats`	`campaign_id`	R, I	מקבל מונים ותוצאות אחרונות.

קולות, חיוב ותיעוד

כלי	ארגומנטים עיקריים	הערות	מה הוא עושה
`list_voices`	—	R, I	מציג קולות ושפות נתמכות.
`preview_voice`	`voice`, `language`, `text`	O	יוצר דוגמה ומחזיר כתובת URL חתומה.
`list_voice_clones`	—	R, I	מציג שכפולי קול מותאמים אישית.
`get_billing_summary`	—	R, I	מחזיר את היתרה ואת מחירי הדרגות הקובעים; לא נחשפות פעולות שינוי תשלום.
`search_docs`	`query`, `limit` אופציונלי	R, I, O	מחפש באינדקס התיעוד הציבורי.
`get_doc_page`	`path`	R, I, O	מאחזר דף תיעוד ציבורי אחד בפורמט Markdown.

כל כלי המוצר משתמשים באותם נתיבי קוד REST כמו ה-API הציבורי. לכן אימות REST, הגדרת היקף ארגון, תפקידים, אישור חיוב, מכסות, אישור TCPA, בטיחות ספקים והתנהגות ביקורת חלים ללא שינוי.

אישור פעולות הרסניות

כלים המסומנים ב-D משנים או מסירים משהו, או מתחילים לחייג לאנשים אמיתיים. כלים שלא ניתן לבטל את פעולתם דורשים שתי בקשות. הבקשה הראשונה אינה משנה דבר ומחזירה:

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

הסוכן מציג למשתמש מה יושפע ומבקש תשובת כן. לאחר מכן הוא חוזר על הבקשה עם אותם ארגומנטים בתוספת confirmation_token. אסימון תקף ל-10 דקות ומכסה ארגון אחד, כלי אחד ומערך מדויק אחד של ארגומנטים, לכן מחיקת שלושה סוכנים דורשת שלושה אישורים. campaign_action עם pause או stop מדלג על שלב זה, כדי שתמיד יהיה אפשר לעצור מיד קמפיין פעיל, וכך גם test_integration עם GET. חלק מהכלים המסומנים ב-D פועלים בבקשה אחת, משום שה-D מציין את השפעתם ולא אישור בצד השרת: update_agent מחליף את מה שהיה בטיוטה (discard_agent_draft מחזיר אותו), deploy_agent מחליף את התצורה הפעילה, update_phone_number מנתב מחדש שיחות פעילות, sync_mcp_server_tools מחליף את קטלוג הכלים של שרת מרוחק, import_voip_numbers מפנה מחדש מספרים אל המפעיל שלכם, run_agent_tests עשוי לצרוך אשראי, send_sms ו-place_call יוצרים קשר עם אדם אמיתי (place_call שומר אישור הסכמה משלו), ו-provision_phone_number רוכש מספר. ייתכן שלקוח ה-MCP שלכם עדיין יבקש מכם לאשר אותם.

הנחיות התחלה

prompts/list מפרסם חמישה תהליכי עבודה לשימוש חוזר:

create_inbound_receptionist
run_agent_tests
buy_and_attach_number
review_low_grade_calls
add_url_to_agent_knowledge

השתמשו ב-prompts/get עם שם ההנחיה המפורט והארגומנטים שהוצהרו עבורה כדי לקבל הודעת משתמש מוכנה להרצה.

משאבים

resources/list חושף הפניות ציבוריות המאוחסנות במטמון:

URI	תוכן
`thunderphone://docs/llms.txt`	אינדקס תיעוד ציבורי.
`thunderphone://docs/quickstart`	Markdown למדריך התחלה מהירה.
`thunderphone://pricing`	Markdown של התמחור הציבורי הנוכחי.

קראו משאב באמצעות resources/read. שליפות ציבוריות משתמשות בפסק זמן קצר, במגבלה של 2 MiB ובמטמון בתוך התהליך למשך עשר דקות.

פרוטוקול ושגיאות

השרת תומך בגרסאות הפרוטוקול 2025-06-18 ו-2025-03-26; הוא מחזיר בהד את גרסת הלקוח הנתמכת, ובמקרים אחרים בוחר ב-2025-06-18. הוא מממש את initialize, ping, כלים, הנחיות, משאבים והתראות. התראות מחזירות 202 Accepted. שרת חסר מצב זה אינו חושף מאזין SSE או מחיקת הפעלה, לכן GET ו-DELETE מחזירים 405 Method Not Allowed עם Allow: POST.

כשלים בכלים נשארים תגובות JSON-RPC מוצלחות עם isError: true. הטקסט שלהן כולל משפט קצר ולאחריו בלוק JSON:

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

הקידומת הייחודית outbound_tcpa_confirmation_required: נשמרת עבור place_call. שיטות JSON-RPC לא מוכרות מחזירות -32601 בתגובת HTTP 200. אצוות JSON-RPC אינן נתמכות על ידי MCP 2025-06-18 ומחזירות שגיאת בקשה לא תקפה -32600 נקייה.