MCP quickstart

The Model Context Protocol lets an assistant call tools directly. Navo24 ships an MCP server per product, so a model can track a box, compare sailings or plan a load without you writing glue code.

The servers

Product	Server	Endpoint	Transport
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

On AirCargoMCP, resolve_awb_prefix answers without a key; track_awb and air_rate_quote need your tmcp_ family key.

Claude Desktop and Cursor

Add a server to your client config. For a Streamable HTTP server, pass the endpoint and your key as a bearer header.

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

A client that only runs local commands reaches any of these servers through mcp-remote. For air cargo:

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

Restart the client and the tools appear. Ask it to track a container and it calls get_container_detail on its own.

What the model can call

Each server exposes the same capabilities as the REST API, named as tools. Tracking offers add_container, get_container_detail, get_shipment_summary and more. Schedules offers find_best_sailings, carrier_reliability and port_congestion. The full tool list sits on each product’s reference page.

Same key, same data

An MCP tool call and a REST call hit the same backend behind the same key. Use MCP where a model drives the work, and REST where your own code does.

Navo Tokens

On an account that holds Navo Tokens, one prepaid balance shared by the Navo products, MCP calls are paid from that balance. The JSON fields that describe the balance keep their credits_ names.

One balance opens every Navo service through MCP: TrackingMCP, AirCargoMCP, FreightRatesMCP, SchedulesMCP and LoadingMCP. You do not need separate MCP access for each product. Two things still stop a call: a product your account manager closed for your account, and a key scoped away from a product (see Access per product below).

MCP and API usage are counted separately. An MCP call never spends an API key’s monthly call limit, and a REST call on your API key never spends Navo Tokens.

Call	Tokens
Track a new container, bill of lading or booking	250
Refresh or read a tracked shipment	10 per reference
Track a new air waybill	200
Refresh an air waybill	10
Freight rates for a port pair	100, or 10 to repeat the pair within 24 hours
Sailing schedules for a port pair	80, or 10 to repeat the pair within 24 hours
A new 3D load plan	50, or 10 per recalculation
Port congestion	10
Schedule reliability, a carrier’s sailings	10
Alerts and webhooks	free

A tool that takes several references costs once per unique reference you submitted. A booking or a bill of lading is one charge for all of its containers. An empty result is free, and a refused call charges nothing. Packages and prices are on the pricing page.

When the balance cannot pay

The call is refused, nothing is charged and no data is returned. The code depends on the product:

Product	Refusal
TrackingMCP	402 INSUFFICIENT_CREDITS
AirCargoMCP	402 with the code insufficient_balance (or trial_expired, wallet_inactive, no_wallet)
FreightRatesMCP	402 with the code insufficient_credits (or trial_expired, wallet_inactive, no_wallet)
SchedulesMCP	429 QUOTA_EXCEEDED before any data is read, or 402 INSUFFICIENT_CREDITS when the balance could no longer pay once the answer was ready
LoadingMCP	402 INSUFFICIENT_CREDITS, refused before the plan is computed

On every product, beside code and message, the error object carries the same four optional fields:

Field	Type	What it holds
credits_required	integer or null	The tokens this call needs; null when the price is not known.
credits_balance	integer or null	The tokens your balance holds now; null when the account has no balance yet.
top_up_url	string or null	The Billing page of your account settings, where you buy more tokens; null when no link can be given.
packages	array of { plan, credits, usd }	The packages you can buy: Starter 7,000 tokens for $69, Growth 40,000 tokens for $349, Scale 200,000 tokens for $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 }
    ]
  }
}

The fields are additive and optional: keep branching on code, and read them when they are present. Every Navo MCP server turns them into the same sentence you can show the user as is: “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).” Each product’s reference page has the details under Navo Tokens.

Access per product

Navo Tokens need no MCP access per product. A product your account manager closed for your account stays closed on Navo Tokens too, for example “Ship Schedules is not enabled for MCP on this account. Ask your account manager.” on SchedulesMCP. A key scoped away from a product is refused with 403, for example “Ship Schedules is not enabled for this API key.” on SchedulesMCP and “Freight Rates is not enabled for this API key. Contact your account manager to open it.” on FreightRatesMCP.