Open in

استخدم ThunderPhone كخادم MCP

أنشئ واختبر وتحقق من صحة وشغّل وكلاء ThunderPhone الصوتيين من Claude أو ChatGPT أو Claude Code أو Codex أو Cursor أو VS Code أو عميل MCP آخر يدعم Streamable HTTP.

يعرض ThunderPhone خادم بروتوكول سياق النموذج عبر HTTP قابلًا للبث على:

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

هذا هو الاتجاه المعاكس لـربط خادم MCP بعيد بوكيل صوتي:

الاتجاه	النتيجة
خادم MCP بعيد → وكيل ThunderPhone	يمكن للوكيل الصوتي استدعاء أدوات الخادم البعيد.
ThunderPhone → عميل MCP لديك	يمكن لوكيل البرمجة لديك بناء ThunderPhone واختباره وتشغيله.

المصادقة

استخدم OAuth افتراضيًا لعملاء الدليل: سجّل الدخول، واختر مؤسسة، ووافق على الأذونات المطلوبة. ألغِ الوصول من المؤسسة → مفاتيح API → التطبيقات المصرح بها.

بالنسبة إلى العملاء المُعَدّين باستخدام مفتاح API، أنشئ مفتاح sk_live_ من المؤسسة → المفاتيح وعرّضه لعميل MCP لديك باسم THUNDERPHONE_API_KEY. يرتبط المفتاح بمؤسسة واحدة؛ ويتصرف المعرّف المملوك لمؤسسة أخرى كما لو أنه غير موجود.

بدائل CLI وstdio

يمكن لـواجهة سطر أوامر 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 المباشر؛ ويستخدم Desktop ‏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`، حقول التوجيه/التسمية/خطاف الويب	D	يحدّث توجيه الرقم، بما في ذلك تعيين الوكيل.
`delete_phone_number`	`phone_number_id`، `confirm`، اختياري `release_at_provider`، و`confirmation_token` في الطلب الثاني	D, I, O	يحرر رقمًا. من خطوتين.

الرسائل النصية القصيرة

الأداة	الوسيطات الرئيسية	التعليقات التوضيحية	ما الذي تفعله
`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	يبحث ضمن الاسترجاع في الإنتاج.

عمليات التكامل وخطافات الويب وخوادم 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	تسرد نقاط نهاية webhook الموقّعة.
`list_webhook_deliveries`	`agent_id` اختياري، و`endpoint_id` اختياري	R، I	تسرد نتائج تسليم webhook الأخيرة من دون حمولات.
`create_webhook_endpoint`	`label`، `url`، وأحداث/حالة اختيارية	O	تنشئ نقطة نهاية webhook موقّعة.
`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. لا يدعم MCP 2025-06-18 دفعات JSON-RPC ويُرجع خطأ طلب غير صالح واضحًا بالقيمة -32600.