Guida rapida MCP

Il Model Context Protocol permette a un assistente di chiamare strumenti direttamente. Navo24 offre un server MCP per la logistica per ogni prodotto: un modello può tracciare un container, confrontare partenze o pianificare un carico senza che tu scriva codice di collegamento.

I server

Prodotto	Server	Endpoint	Trasporto
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

Su AirCargoMCP, resolve_awb_prefix risponde senza chiave; track_awb e air_rate_quote richiedono la tua chiave della famiglia tmcp_.

Claude Desktop e Cursor

Aggiungi un server alla configurazione del tuo client. Per un server Streamable HTTP indica l’endpoint e la tua chiave come header bearer.

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

Un client che esegue solo comandi locali raggiunge uno qualsiasi di questi server tramite mcp-remote. Per il cargo aereo:

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

Riavvia il client e compaiono gli strumenti. Chiedigli di tracciare un container e chiamerà get_container_detail da solo.

Cosa può chiamare il modello

Ogni server espone le stesse funzioni dell’API REST, sotto forma di strumenti. Tracking offre add_container, get_container_detail, get_shipment_summary e altri. Schedules offre find_best_sailings, carrier_reliability e port_congestion. L’elenco completo degli strumenti è nella pagina di riferimento di ogni prodotto.

Stessa chiave, stessi dati

Una chiamata a uno strumento MCP e una chiamata REST arrivano allo stesso backend con la stessa chiave. Usa MCP quando il lavoro lo guida un modello, REST quando lo fa il tuo codice.

Navo Tokens

Su un account che dispone di Navo Tokens, un unico saldo prepagato condiviso dai prodotti Navo, le chiamate MCP vengono pagate da quel saldo. I campi JSON che descrivono il saldo mantengono i loro nomi credits_.

Un solo saldo apre tutti i servizi Navo tramite MCP: TrackingMCP, AirCargoMCP, FreightRatesMCP, SchedulesMCP e LoadingMCP. Non serve un accesso MCP separato per ogni prodotto. Due cose bloccano comunque una chiamata: un prodotto che il tuo account manager ha chiuso per il tuo account e una chiave il cui ambito esclude un prodotto (vedi Accesso per prodotto più avanti).

L’uso MCP e quello API vengono conteggiati separatamente. Una chiamata MCP non consuma mai il limite mensile di chiamate di una chiave API, e una chiamata REST con la tua chiave API non consuma mai Navo Tokens.

Chiamata	Token
Tracciare un nuovo container, polizza di carico o booking	250
Aggiornare o leggere una spedizione tracciata	10 per riferimento
Tracciare una nuova lettera di vettura aerea	200
Aggiornare una lettera di vettura aerea	10
Tariffe di nolo per una coppia di porti	100, oppure 10 se ripeti la coppia entro 24 ore
Orari delle partenze per una coppia di porti	80, oppure 10 se ripeti la coppia entro 24 ore
Un nuovo piano di carico 3D	50, oppure 10 per ogni ricalcolo
Congestione portuale	10
Affidabilità degli orari, partenze di un vettore	10
Alert e webhook	gratis

Uno strumento che accetta più riferimenti addebita una volta per ogni riferimento univoco inviato. Un booking o una polizza di carico è un unico addebito per tutti i suoi container. Un risultato vuoto è gratuito e una chiamata rifiutata non costa nulla. Pacchetti e prezzi sono nella pagina dei prezzi.

Quando il saldo non basta

La chiamata viene rifiutata, non viene addebitato nulla e non vengono restituiti dati. Il codice dipende dal prodotto:

Prodotto	Rifiuto
TrackingMCP	402 INSUFFICIENT_CREDITS
AirCargoMCP	402 con il codice insufficient_balance (oppure trial_expired, wallet_inactive, no_wallet)
FreightRatesMCP	402 con il codice insufficient_credits (oppure trial_expired, wallet_inactive, no_wallet)
SchedulesMCP	429 QUOTA_EXCEEDED prima di leggere qualsiasi dato, oppure 402 INSUFFICIENT_CREDITS quando il saldo non bastava più una volta pronta la risposta
LoadingMCP	402 INSUFFICIENT_CREDITS, rifiutata prima del calcolo del piano

Su ogni prodotto, oltre a code e message, l’oggetto error contiene gli stessi quattro campi opzionali:

Campo	Tipo	Contenuto
credits_required	intero o null	I token necessari per questa chiamata; null quando il prezzo non è noto.
credits_balance	intero o null	I token presenti ora nel tuo saldo; null quando l’account non ha ancora un saldo.
top_up_url	stringa o null	La pagina Billing delle impostazioni del tuo account, dove acquisti altri token; null quando non è possibile fornire un link.
packages	array di { plan, credits, usd }	I pacchetti che puoi acquistare: Starter, 7.000 token a $69; Growth, 40.000 token a $349; Scale, 200.000 token a $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 }
    ]
  }
}

I campi sono aggiuntivi e opzionali: continua a basare la logica su code e leggili quando sono presenti. Ogni server MCP di Navo li trasforma nella stessa frase, che puoi mostrare all’utente così com’è: “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).” La pagina di riferimento di ogni prodotto riporta i dettagli nella sezione Navo Tokens.

Accesso per prodotto

Navo Tokens non richiede un accesso MCP per prodotto. Un prodotto che il tuo account manager ha chiuso per il tuo account resta chiuso anche con Navo Tokens, ad esempio “Ship Schedules is not enabled for MCP on this account. Ask your account manager.” su SchedulesMCP. Una chiave il cui ambito esclude un prodotto viene rifiutata con 403, ad esempio “Ship Schedules is not enabled for this API key.” su SchedulesMCP e “Freight Rates is not enabled for this API key. Contact your account manager to open it.” su FreightRatesMCP.