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

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

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

هذا هو الاتجاه المعاكس لـ[ربط خادم MCP بعيد بوكيل صوتي](/ar/guides/mcp-servers):

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

## المصادقة

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

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

<Warning>
  يمكن لمفتاح `sk_live_` قراءة بيانات المؤسسة وتنفيذ إجراءات إنتاجية مثل نشر الوكلاء وإجراء المكالمات وشراء الأرقام وبدء الحملات وحذف الموارد. أبقه خارج شفرة المتصفح والمستودعات ولقطات الشاشة وسجلات الدردشة. استخدم مخزن الأسرار أو دعم البيئة في عميلك، وألغِ مفتاحًا مكشوفًا فورًا.
</Warning>

## بدائل CLI وstdio

يمكن لـ[واجهة سطر أوامر ThunderPhone](/ar/guides/cli) كتابة إعدادات العميل مع الحفاظ على
الخوادم غير ذات الصلة:

```bash
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](/ar/guides/oauth)؛ ولا يلزم مفتاح API. إذا لم يكن لديك حساب ThunderPhone بعد، فاختر **إنشاء حساب** في صفحة تسجيل الدخول، ثم ستعود إلى شاشة الموافقة بعد التحقق من بريدك الإلكتروني.

### Claude (الويب وسطح المكتب والجوال)

1. افتح **تخصيص → الموصلات** (**الإعدادات → الموصلات** في الإصدارات الأقدم). إذا ظهر ThunderPhone في دليل الموصلات، فحدده. وإلا فاختر **إضافة موصل مخصص**، وسمّه `ThunderPhone`، وأدخل `https://api.thunderphone.com/v1/mcp`.
2. اختر **اتصال**، وسجّل الدخول إلى ThunderPhone، واختر المؤسسة، ثم وافق على الأذونات.
3. في محادثة، فعّل ThunderPhone من قائمة الأدوات واطلب ما تحتاج إليه، مثل "اعرض وكلائي".

يطلب Claude الموافقة قبل استخدام كل أداة للمرة الأولى. لتجاوز معظم هذه الموجّهات، افتح **تخصيص → الموصلات → ThunderPhone** واضبط **أدوات القراءة فقط** على السماح دائمًا. هذه الأدوات تبحث عن المعلومات فقط: الوكلاء والمكالمات والنصوص المفرغة والأرصدة والوثائق. اترك **أدوات الكتابة/الحذف** على طلب الموافقة إذا كنت تريد رؤية كل تغيير قبل حدوثه.

تتطلب الموصلات المخصصة باقة Claude مدفوعة. في باقتي Team وEnterprise، يضيف مالك المؤسسة الموصل ضمن إعدادات موصلات المؤسسة أولًا، ثم يربط كل عضو حساب ThunderPhone الخاص به.

### ChatGPT

1. إذا ظهر ThunderPhone في دليل تطبيقات ChatGPT، فحدده واتصل به.
2. وإلا فافتح **الإعدادات → التطبيقات والموصلات → الإعدادات المتقدمة**، وشغّل **وضع المطوّر**، ثم أنشئ موصلًا بعنوان URL هو `https://api.thunderphone.com/v1/mcp` وبمصادقة OAuth.
3. سجّل الدخول إلى ThunderPhone، واختر المؤسسة، ثم وافق على الأذونات. أضف ThunderPhone إلى محادثة من قائمة الأدوات.

يتطلب حذف وكيل أو رقم هاتف، أو تجاهل مسودة، أو إطلاق حملة، أو إرسال طلب اختبار يمكنه الكتابة إلى نظام خارجي، تأكيدًا ثانيًا في أيٍّ من التطبيقين؛ راجع [تأكيد الإجراءات المدمرة](#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

أضف ما يلي إلى `~/.codex/config.toml`:

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

### Cursor

أنشئ `.cursor/mcp.json`:

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

### Claude Desktop

أضف جسر `mcp-remote` إلى إعدادات 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

أنشئ `.vscode/mcp.json` وأدخل المفتاح عبر موجّه الإدخال في 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}"
      }
    }
  }
}
```

## الأدوات

تحمل كل أداة تعليقات 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 | يتجاهل التغييرات المهيّأة. من خطوتين، راجع [تأكيد الإجراءات المدمرة](#confirming-destructive-actions). |
| `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 تغيّر شيئًا أو تزيله، أو تبدأ الاتصال بأشخاص حقيقيين. الأدوات التي لا يمكن التراجع عنها تتطلب طلبين. لا يغيّر الطلب الأول شيئًا ويعيد ما يلي:

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

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