البدء السريع مع MCP

يتيح Model Context Protocol للمساعد استدعاء الأدوات مباشرة. توفّر Navo24 خادم MCP للخدمات اللوجستية لكل منتج، فيستطيع النموذج تتبع حاوية أو مقارنة الرحلات أو تخطيط حمولة من دون أن تكتب شيفرة ربط.

الخوادم

المنتج	الخادم	Endpoint	النقل
TrackingMCP	container-tracking	https://mcp.trackingmcp.com/mcp	Streamable HTTP
SchedulesMCP	ocean-schedules	https://mcp.schedulesmcp.com/mcp	Streamable HTTP
LoadingMCP	container-loading	https://mcp.loadingmcp.com/mcp	Streamable HTTP
AirCargoMCP	air-cargo	https://mcp.aircargomcp.com/mcp	Streamable HTTP
FreightRatesMCP	freight-rates	https://mcp.freightratesmcp.com/mcp	Streamable HTTP

في AirCargoMCP تجيب resolve_awb_prefix من دون مفتاح، أما track_awb وair_rate_quote فتحتاجان إلى مفتاح عائلة tmcp_ الخاص بك.

Claude Desktop وCursor

أضف خادمًا إلى إعدادات العميل. مع خادم Streamable HTTP مرّر الـ endpoint ومفتاحك في ترويسة bearer.

{
  "mcpServers": {
    "container-tracking": {
      "url": "https://mcp.trackingmcp.com/mcp",
      "headers": { "Authorization": "Bearer tmcp_YOUR_API_KEY" }
    }
  }
}

العميل الذي لا يشغّل إلا أوامر محلية يصل إلى أيٍّ من هذه الخوادم عبر mcp-remote. للشحن الجوي:

{
  "mcpServers": {
    "air-cargo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.aircargomcp.com/mcp",
               "--header", "Authorization: Bearer tmcp_YOUR_API_KEY"]
    }
  }
}

أعد تشغيل العميل فتظهر الأدوات. اطلب منه تتبع حاوية وسيستدعي get_container_detail بنفسه.

ما الذي يستطيع النموذج استدعاءه

يقدّم كل خادم القدرات نفسها التي تقدّمها REST API، لكن في صورة أدوات. في Tracking توجد add_container وget_container_detail وget_shipment_summary وغيرها. وفي Schedules توجد find_best_sailings وcarrier_reliability وport_congestion. القائمة الكاملة للأدوات موجودة في الصفحة المرجعية لكل منتج.

المفتاح نفسه والبيانات نفسها

استدعاء أداة MCP واستدعاء REST يصلان إلى الـ backend نفسه بالمفتاح نفسه. استخدم MCP حين يقود النموذج العمل، وREST حين تقوده شيفرتك.

Navo Tokens

في الحساب الذي يملك Navo Tokens، وهو رصيد مسبق الدفع واحد تتشاركه منتجات Navo، تُدفع استدعاءات MCP من هذا الرصيد. وتحتفظ حقول JSON التي تصف الرصيد بأسمائها التي تبدأ بـ credits_.

رصيد واحد يفتح كل خدمات Navo عبر MCP: TrackingMCP وAirCargoMCP وFreightRatesMCP وSchedulesMCP وLoadingMCP. لا تحتاج إلى وصول MCP منفصل لكل منتج. لكن أمرين ما زالا يوقفان الاستدعاء: منتج أغلقه مدير حسابك لحسابك، ومفتاح نطاقه يستثني منتجًا ما (راجع قسم الوصول حسب المنتج أدناه).

يُحتسب استخدام MCP واستخدام API كلٌّ على حدة. استدعاء MCP لا يستهلك أبدًا الحد الشهري لاستدعاءات مفتاح API، واستدعاء REST بمفتاح API الخاص بك لا يستهلك أبدًا Navo Tokens.

الاستدعاء	التوكنات
تتبع حاوية جديدة أو بوليصة شحن أو حجز	250
تحديث شحنة متتبَّعة أو قراءتها	10 لكل مرجع
تتبع بوليصة شحن جوي جديدة	200
تحديث بوليصة شحن جوي	10
أسعار الشحن لزوج من الموانئ	100، أو 10 عند تكرار الزوج نفسه خلال 24 ساعة
جداول الإبحار لزوج من الموانئ	80، أو 10 عند تكرار الزوج نفسه خلال 24 ساعة
خطة تحميل 3D جديدة	50، أو 10 لكل إعادة حساب
ازدحام الموانئ	10
موثوقية الجداول، رحلات ناقل معيّن	10
التنبيهات والـ webhooks	مجانًا

الأداة التي تقبل عدة مراجع تُحتسب مرة واحدة لكل مرجع فريد أرسلته. والحجز أو بوليصة الشحن رسم واحد لكل حاوياته. النتيجة الفارغة مجانية، والاستدعاء المرفوض لا يُحتسب عليه شيء. الباقات والأسعار في صفحة الأسعار.

عندما لا يكفي الرصيد للدفع

يُرفض الاستدعاء، ولا يُخصم شيء، ولا تُعاد أي بيانات. ويختلف الرمز حسب المنتج:

المنتج	الرفض
TrackingMCP	402 INSUFFICIENT_CREDITS
AirCargoMCP	402 مع الرمز insufficient_balance (أو trial_expired، wallet_inactive، no_wallet)
FreightRatesMCP	402 مع الرمز insufficient_credits (أو trial_expired، wallet_inactive، no_wallet)
SchedulesMCP	429 QUOTA_EXCEEDED قبل قراءة أي بيانات، أو 402 INSUFFICIENT_CREDITS حين لم يعد الرصيد كافيًا للدفع بعد أن أصبحت الإجابة جاهزة
LoadingMCP	402 INSUFFICIENT_CREDITS، ويُرفض الاستدعاء قبل حساب الخطة

في كل المنتجات، إلى جانب code وmessage، يحمل الكائن error الحقول الاختيارية الأربعة نفسها:

الحقل	النوع	محتواه
credits_required	integer أو null	عدد التوكنات التي يحتاجها هذا الاستدعاء؛ null حين يكون السعر غير معروف.
credits_balance	integer أو null	عدد التوكنات في رصيدك الآن؛ null حين لا يملك الحساب رصيدًا بعد.
top_up_url	string أو null	صفحة Billing في إعدادات حسابك، حيث تشتري مزيدًا من التوكنات؛ null حين لا يمكن تقديم رابط.
packages	مصفوفة من { plan, credits, usd }	الباقات المتاحة للشراء: Starter بـ 7,000 توكن مقابل $69، وGrowth بـ 40,000 توكن مقابل $349، وScale بـ 200,000 توكن مقابل $1,399.

{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough Navo Tokens: this needs 10, your balance is 4. Buy more tokens: https://app.trackingmcp.com/settings?tab=billing&buy=credits (Starter 7,000 tokens for $69, Growth 40,000 tokens for $349, Scale 200,000 tokens for $1,399).",
    "severity": "warning",
    "credits_required": 10,
    "credits_balance": 4,
    "top_up_url": "https://app.trackingmcp.com/settings?tab=billing&buy=credits",
    "packages": [
      { "plan": "starter", "credits": 7000, "usd": 69 },
      { "plan": "growth", "credits": 40000, "usd": 349 },
      { "plan": "scale", "credits": 200000, "usd": 1399 }
    ]
  }
}

هذه الحقول إضافية واختيارية: واصل التفرّع بناءً على code، واقرأها حين تكون موجودة. يحوّلها كل خادم MCP من Navo إلى الجملة نفسها التي يمكنك عرضها على المستخدم كما هي: “Not enough Navo Tokens: this needs 10, your balance is 4. Buy more tokens: <link> (Starter 7,000 tokens for $69, Growth 40,000 tokens for $349, Scale 200,000 tokens for $1,399).” وتجد التفاصيل في الصفحة المرجعية لكل منتج تحت قسم Navo Tokens.

الوصول حسب المنتج

لا تحتاج Navo Tokens إلى وصول MCP لكل منتج. المنتج الذي أغلقه مدير حسابك لحسابك يبقى مغلقًا مع Navo Tokens أيضًا، مثل “Ship Schedules is not enabled for MCP on this account. Ask your account manager.” في SchedulesMCP. والمفتاح الذي يستثني نطاقُه منتجًا ما يُرفض بالرمز 403، مثل “Ship Schedules is not enabled for this API key.” في SchedulesMCP و”Freight Rates is not enabled for this API key. Contact your account manager to open it.” في FreightRatesMCP.