سرور MCP لجستیک: شروع سریع با Claude و Cursor

شروع سریع سرور MCP لجستیک: Claude، Cursor یا هر کلاینت MCP را به Navo24 وصل کنید تا مدل خودش کانتینرها را ردیابی کند و سفرها را مقایسه کند.

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
هشدارها و webhookها	رایگان

ابزاری که چند شناسه می‌گیرد، برای هر شناسه یکتایی که ارسال کرده‌اید یک بار هزینه دارد. یک رزرو یا بارنامه برای همه کانتینرهایش یک هزینه است. نتیجه خالی رایگان است و برای فراخوانی ردشده هیچ هزینه‌ای کسر نمی‌شود. بسته‌ها و قیمت‌ها در صفحه قیمت‌گذاری آمده است.

وقتی موجودی کافی نیست

فراخوانی رد می‌شود، هزینه‌ای کسر نمی‌شود و داده‌ای برگردانده نمی‌شود. کد خطا به محصول بستگی دارد:

محصول	رد درخواست
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`، پیش از محاسبه طرح رد می‌شود

در همه محصولات، شیء error در کنار code و message همان چهار فیلد اختیاری را دارد:

فیلد	نوع	محتوا
`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 هم بسته می‌ماند؛ برای مثال در SchedulesMCP: “Ship Schedules is not enabled for MCP on this account. Ask your account manager.” کلیدی که دامنه دسترسی‌اش یک محصول را شامل نمی‌شود با 403 رد می‌شود؛ برای مثال در SchedulesMCP: “Ship Schedules is not enabled for this API key.” و در FreightRatesMCP: “Freight Rates is not enabled for this API key. Contact your account manager to open it.”