Guia rápido de MCP

O Model Context Protocol permite que um assistente chame ferramentas diretamente. A Navo24 tem um servidor MCP de logística por produto, por isso um modelo pode rastrear um contentor, comparar saídas ou planear uma carga sem que escreva código de integração.

Os servidores

Produto	Servidor	Endpoint	Transporte
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

No AirCargoMCP, resolve_awb_prefix responde sem chave; track_awb e air_rate_quote precisam da sua chave da família tmcp_.

Claude Desktop e Cursor

Adicione um servidor à configuração do seu cliente. Num servidor Streamable HTTP, indique o endpoint e a sua chave como cabeçalho bearer.

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

Um cliente que só executa comandos locais chega a qualquer um destes servidores através do mcp-remote. Para carga aérea:

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

Reinicie o cliente e as ferramentas aparecem. Peça-lhe para rastrear um contentor e ele chama get_container_detail sozinho.

O que o modelo pode chamar

Cada servidor expõe as mesmas funções da API REST, com nomes de ferramentas. O Tracking oferece add_container, get_container_detail, get_shipment_summary e outras. O Schedules oferece find_best_sailings, carrier_reliability e port_congestion. A lista completa de ferramentas está na página de referência de cada produto.

A mesma chave, os mesmos dados

Uma chamada de ferramenta MCP e uma chamada REST chegam ao mesmo backend com a mesma chave. Use MCP quando é um modelo a conduzir o trabalho, e REST quando é o seu próprio código.

Navo Tokens

Numa conta que dispõe de Navo Tokens, um saldo pré-pago único partilhado pelos produtos Navo, as chamadas MCP são pagas a partir desse saldo. Os campos JSON que descrevem o saldo mantêm os nomes credits_.

Um único saldo dá acesso a todos os serviços Navo através de MCP: TrackingMCP, AirCargoMCP, FreightRatesMCP, SchedulesMCP e LoadingMCP. Não precisa de um acesso MCP separado para cada produto. Há duas coisas que continuam a bloquear uma chamada: um produto que o seu gestor de conta fechou para a sua conta e uma chave cujo âmbito exclui um produto (ver Acesso por produto mais abaixo).

A utilização de MCP e a da API são contabilizadas separadamente. Uma chamada MCP nunca gasta o limite mensal de chamadas de uma chave de API, e uma chamada REST com a sua chave de API nunca gasta Navo Tokens.

Chamada	Tokens
Rastrear um novo contentor, conhecimento de embarque ou booking	250
Atualizar ou consultar um envio rastreado	10 por referência
Rastrear uma nova carta de porte aéreo	200
Atualizar uma carta de porte aéreo	10
Tarifas de frete para um par de portos	100, ou 10 para repetir o par no prazo de 24 horas
Horários de saídas para um par de portos	80, ou 10 para repetir o par no prazo de 24 horas
Um novo plano de carga 3D	50, ou 10 por cada novo cálculo
Congestionamento portuário	10
Fiabilidade dos horários, saídas de um armador	10
Alertas e webhooks	grátis

Uma ferramenta que aceita várias referências cobra uma vez por cada referência única enviada. Um booking ou um conhecimento de embarque é uma única cobrança para todos os seus contentores. Um resultado vazio é gratuito e uma chamada recusada não cobra nada. Os pacotes e preços estão na página de preços.

Quando o saldo não chega

A chamada é recusada, nada é cobrado e não são devolvidos dados. O código depende do produto:

Produto	Recusa
TrackingMCP	402 INSUFFICIENT_CREDITS
AirCargoMCP	402 com o código insufficient_balance (ou trial_expired, wallet_inactive, no_wallet)
FreightRatesMCP	402 com o código insufficient_credits (ou trial_expired, wallet_inactive, no_wallet)
SchedulesMCP	429 QUOTA_EXCEEDED antes de ser lido qualquer dado, ou 402 INSUFFICIENT_CREDITS quando o saldo já não chegava depois de a resposta estar pronta
LoadingMCP	402 INSUFFICIENT_CREDITS, recusada antes de o plano ser calculado

Em todos os produtos, além de code e message, o objeto error inclui os mesmos quatro campos opcionais:

Campo	Tipo	O que contém
credits_required	inteiro ou null	Os tokens de que esta chamada precisa; null quando o preço não é conhecido.
credits_balance	inteiro ou null	Os tokens que o seu saldo tem neste momento; null quando a conta ainda não tem saldo.
top_up_url	string ou null	A página Billing das definições da sua conta, onde compra mais tokens; null quando não é possível indicar um link.
packages	array de { plan, credits, usd }	Os pacotes que pode comprar: Starter, 7.000 tokens por $69; Growth, 40.000 tokens por $349; Scale, 200.000 tokens por $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 }
    ]
  }
}

Os campos são adicionais e opcionais: continue a basear a lógica em code e leia-os quando estiverem presentes. Todos os servidores MCP da Navo transformam-nos na mesma frase, que pode mostrar ao utilizador tal como está: “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).” A página de referência de cada produto tem os detalhes na secção Navo Tokens.

Acesso por produto

Os Navo Tokens não exigem acesso MCP por produto. Um produto que o seu gestor de conta fechou para a sua conta continua fechado também com Navo Tokens, por exemplo “Ship Schedules is not enabled for MCP on this account. Ask your account manager.” no SchedulesMCP. Uma chave cujo âmbito exclui um produto é recusada com 403, por exemplo “Ship Schedules is not enabled for this API key.” no SchedulesMCP e “Freight Rates is not enabled for this API key. Contact your account manager to open it.” no FreightRatesMCP.