SchedulesMCP

Compare sailings the way a freight desk actually books them.

Base URL

https://api.schedulesmcp.com

The /public prefix is historical and does not mean open: the data endpoints under it need a key. Only the carrier list and the port search are open. Read the badge on each endpoint.

Authentication

Authorization: Bearer smcp_…

Use a key minted for SchedulesMCP (smcp_). Your organisation's shared tmcp_ key is accepted too; calls made with it count against the same SchedulesMCP limit. See the authentication guide.

Public responses wrap in { "ok": true, "data": … }. Ports and locations are UN/LOCODEs (for example CNSHA, NLRTM).

Publishes sailings for 65 shipping lines, filterable by their SCAC codes.View supported lines →

OpenAPI spec Import the spec into Postman or Insomnia, or generate a typed client with openapi-generator.

Endpoints

Schedules

GETUpcoming sailings/public/schedules GETCarriers you can filter for/public/schedules/carriers

Reliability

GETReliability on a lane/public/reliability/lanes GETCarrier league table/public/reliability/leaderboard

Ports

GETResolve a port/public/ports/search GETPort congestion/public/port-congestion

Webhooks

POSTRegister an endpoint/v1/webhooks GETList endpoints/v1/webhooks GETEndpoint detail and deliveries/v1/webhooks/{id}PATCHUpdate an endpoint/v1/webhooks/{id}DELETEDelete an endpoint/v1/webhooks/{id}POSTSend a test delivery/v1/webhooks/{id}/test

MCP server

The ocean-schedules server exposes the same capabilities as tool calls over Streamable HTTP. Point any MCP client at the endpoint below. See the MCP quickstart.

MCP endpoint

https://mcp.schedulesmcp.com/mcp

find_sailingsUpcoming sailings on a lane, vessel-first.

find_best_sailingsRank sailings by reliability, transit and departure.

compare_lanesPut two or more lanes side by side.

carrier_reliabilityOn-time record for carriers on a lane.

carrier_leagueCarrier on-time league table.

transit_timeTypical and observed transit for a lane.

port_congestionCongestion and dwell at a port.

lane_storm_exposureActive-cyclone exposure along a lane.

Navo Tokens

On an account that holds Navo Tokens, one prepaid balance shared by the Navo products, MCP calls are paid from that balance. One balance opens every Navo service through MCP (TrackingMCP, AirCargoMCP, FreightRatesMCP, SchedulesMCP and LoadingMCP): no separate MCP access per product is needed. A product your account manager closed for your account stays closed, and a key scoped away from a product cannot reach it. 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. An empty result is free, and a refused call charges nothing. Alerts and webhooks are free. Prices and packages are on the pricing page.

Prices.

– A lane search (find_sailings, find_best_sailings, GET /public/schedules): 80 tokens for a new port pair, 10 to repeat the same pair within 24 hours.
– Reliability, a carrier's sailings and port congestion: 10 tokens a call.
– Alerts and webhooks: free.

An empty answer is always free.

MCP access. An MCP call is an API-key call carrying X-Schedules-Surface: mcp, or a call signed in through an MCP client's OAuth sign-in. Without Navo Tokens it is held by your account's MCP access, never its API access; without that access it is 403 FORBIDDEN, "Ship Schedules is not enabled for MCP on this account. Ask your account manager." With Navo Tokens no MCP access is needed: only MCP access your account manager closed refuses the call, with the same message. A key scoped away from Ship Schedules gets 403 FORBIDDEN, "Ship Schedules is not enabled for this API key."

When the balance cannot pay. The call is refused with 429 QUOTA_EXCEEDED before any data is read, or, if the balance could no longer pay once the answer was ready, 402 INSUFFICIENT_CREDITS ("Token balance too low for this lookup. Buy more tokens or contact your account owner."), nothing is charged and no data is returned. Beside code and message, the error object carries four optional fields, the same on every Navo service:

– credits_required (integer, or null when the price is not known): the tokens this call needs;
– credits_balance (integer, or null when the account has no balance yet): the tokens your balance holds now;
– top_up_url (string): the Billing page of your account settings, where you buy more tokens, or null when no link can be given;
– packages (array of { plan, credits, usd }): the token packages you can buy, Starter 7,000 tokens for $69, Growth 40,000 tokens for $349, Scale 200,000 tokens for $1,399.

The fields are additive and optional. Keep branching on code, and read them when they are present.

The MCP server turns the fields into one sentence you can show the user as is, for example: "Not enough Navo Tokens: this needs 80, your balance is 30. Buy more tokens: <link> (Starter 7,000 tokens for $69, Growth 40,000 tokens for $349, Scale 200,000 tokens for $1,399)."

A refusal for a balance that cannot pay

{
  "ok": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "schedules quota reached.",
    "credits_required": 80,
    "credits_balance": 30,
    "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 }
    ]
  }
}

How calls are counted

Data needs a key and is counted. GET /public/schedules, /public/reliability/lanes, /public/reliability/leaderboard and /public/port-congestion need an API key. Each answer that carries data is 1 call against your account's monthly call limit.

/public/reliability/lanes, /public/reliability/leaderboard and /public/port-congestion need an API key. A call without a key gets 401.

Reference lists are open. GET /public/schedules/carriers and /public/ports/search need no key and are never counted.

Sailing cards (/public/schedules/cards) are not available: 403 FORBIDDEN.

Not counted:

– an empty answer, when nothing was found;
– the next pages of the same search;
– refusals and errors.

Webhooks. Every successful request you make to /v1/webhooks and its sub-paths is 1 call. The event deliveries we send to your endpoint are free. Registering, updating and testing an endpoint need SchedulesMCP connected to your account.