الاتصال عبر MCP

استخدم مفتاح Narwhal نفسه ومخططات API العامة نفسها من عميل MCP.

يوفر Narwhal نقطة نهاية MCP واحدة عديمة الحالة عبر Streamable HTTP. وتستخدم واجهات API للبيانات المفعّلة ومخططات الاستجابة والمصادقة والحصة نفسها التي تستخدمها REST.

اتصال

أضف عنوان الخادم البعيد وترويسة Bearer إلى عميل MCP يدعم Streamable HTTP المصادق عليه.

خريطة الحقول المحايدة للعميل

{
  "url": "https://api.narwhalapi.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_NARWHAL_API_KEY"
  }
}

هذه خريطة حقول، وليست ملفاً جاهزاً للنسخ واللصق. استبدل YOUR_NARWHAL_API_KEY من خلال إعداد تخزين الأسرار الآمن في عميلك. لا يستبدل JSON متغيرات الصدفة بقيمها تلقائيًا، وتستخدم برامج عميل MCP صيغًا مختلفة لمتغيرات البيئة.

لا تلصق مفتاحًا حقيقيًا في ملف إعدادات مشترك.

الأدوات المتاحة

tools/list يعيد الأدوات العامة المخصّصة للقراءة فقط والمفعّلة لملف إعداد هذا الإصدار. القائمة أدناه هي مجموعة الأدوات العامة، وليست وعدًا بأن لكل مصدر قيمة لكل إدخال.

economics_get_cpieconomics_get_inflationeconomics_get_unemploymenteconomics_get_labour_force_participationeconomics_get_gdpeconomics_get_gdp_growtheconomics_get_tradeeconomics_get_cpi_historyeconomics_get_inflation_historyeconomics_get_unemployment_historyeconomics_get_labour_force_participation_historyeconomics_get_gdp_historyeconomics_get_gdp_growth_historyeconomics_get_trade_historyeconomics_read_series_observationsfx_get_ratesfx_get_rate_historyfx_convert_currencyfx_get_rate_barscommodities_get_spot_pricecommodities_get_price_historycommodities_list_palmoil_physical_seriescommodities_get_palmoil_physical_pricecommodities_get_palmoil_physical_observationscommodities_list_physical_seriescommodities_get_physical_seriescommodities_get_physical_latestcommodities_get_physical_observationseconomics_list_releaseseconomics_get_releaseevents_listevents_getpredictions_list_topicspredictions_get_topicpredictions_list_eventspredictions_get_scalarpredictions_get_extremepredictions_get_timingpredictions_get_binarypredictions_get_scalar_historypredictions_get_extreme_historypredictions_get_timing_historypredictions_get_binary_historypredictions_get_policy_pathpredictions_get_policy_path_historycalendars_list_holidayscalendars_get_holidays_on_datecalendars_get_next_holidayeconomics_get_yield_curveeconomics_get_yield_curve_history

الوسيطات والنتائج

تقبل أدوات الإصدار الأحدث country، اختياري period واختياريًا version_id. تقبل أدوات السجل country، اختياري start و end، بالإضافة إلى limit و cursor لترقيم الصفحات.

وسيطات الأداة

{
  "country": "USA",
  "period": "2026-07"
}

الأداة	الفترة	وسيطات أخرى
`economics_get_cpi`	`YYYY-MM`	`version_id`
`economics_get_inflation`	`YYYY-MM`	`version_id`
`economics_get_unemployment`	`YYYY, YYYY-MM, or YYYY-QN`	`version_id`
`economics_get_labour_force_participation`	`YYYY, YYYY-MM, or YYYY-QN`	`version_id`
`economics_get_gdp`	`YYYY-QN`	`version_id`
`economics_get_gdp_growth`	`YYYY-QN`	`version_id`
`economics_get_trade`	`YYYY or YYYY-MM`	`version_id`
`economics_get_cpi_history`	`YYYY-MM`	`start`, `end`, `limit`، و `cursor`
`economics_get_inflation_history`	`YYYY-MM`	`start`, `end`, `limit`، و `cursor`
`economics_get_unemployment_history`	`YYYY, YYYY-MM, or YYYY-QN`	`start`, `end`, `limit`، و `cursor`
`economics_get_labour_force_participation_history`	`YYYY, YYYY-MM, or YYYY-QN`	`start`, `end`, `limit`، و `cursor`
`economics_get_gdp_history`	`YYYY-QN`	`start`, `end`, `limit`، و `cursor`
`economics_get_gdp_growth_history`	`YYYY-QN`	`start`, `end`, `limit`، و `cursor`
`economics_get_trade_history`	`YYYY-MM`	`start`, `end`, `limit`، و `cursor`

تعيد استدعاءات الأدوات الناجحة محتوى مطابقًا للمخطط في structuredContent بالإضافة إلى بيانات JSON نفسها محوّلةً إلى نص لضمان التوافق مع العملاء. تستخدم تفاصيل أخطاء MCP مصطلحات الحالات والرموز العامة نفسها المستخدمة في REST.

سلوك الحصة

لا تستهلك التهيئة واكتشاف الأدوات حصة البيانات. وكل استدعاء ناجح tools/call يستهلك طلباً واحداً بالضبط، مثل استدعاء REST ناجح واحد.

أول استدعاء للأداة

{
  "method": "tools/call",
  "params": {
    "name": "fx_get_rates",
    "arguments": { "base": "USD", "currencies": ["EUR", "JPY"] }
  }
}

يتضمن الإصدار التجريبي لخطة Free 5,000 طلب ناجح لكل شهر بتوقيت UTC، بالإضافة إلى 30 طلبًا في الدقيقة. تُعاد حالة الحصة في X-RateLimit-Limit, X-RateLimit-Remaining، و X-RateLimit-Reset؛ تُعاد حالة الفترة الزمنية القصيرة في X-RateLimit-Short-Limit, X-RateLimit-Short-Remaining، و X-RateLimit-Short-Reset. يعيد تقييد الطلبات خلال الفترة الزمنية القصيرة 429 rate_limit_exceeded؛ يعيد استنفاد الحصة الشهرية 429 quota_exhausted.

استكشاف الأخطاء وإصلاحها

العَرَض	تحقّق
`401 invalid_api_key`	تحقّق من صحة ترويسة Bearer ومن أن المفتاح ما زال نشطًا.
يتبع الاتصال إعادة توجيه	استخدم بالضبط `https://api.narwhalapi.com/mcp` من دون شرطة مائلة في النهاية.
الأداة مفقودة	لا تتوفر إلا الأدوات العامة المذكورة أعلاه.
تعيد الأداة تفاصيل خطأ	اقرأ الحقول المنظّمة status وcode وdetail ومعرّف الطلب. راجع الأخطاء والحصة.