Docs

MCP server

AIS Trail runs a Model Context Protocol (MCP) server with read-only tools, so Claude, ChatGPT, Cursor or any other MCP client can find ships, follow them and list their port calls when you ask in plain words. The live tools work without a key; the archive tools use your API key and your plan's credits, exactly as the REST API does.

Server

URL. https://api.aistrail.com/mcp
Transport. Streamable HTTP without sessions: every request gets one JSON response (no server-sent events; GET and DELETE answer 405).
Protocol versions. 2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26.
Authentication. vessel_track, vessel_port_calls and port_calls need your API key as the HTTP header Authorization: Bearer ap_live_…; the other tools need no key.

Connect a client

In Claude Code, add the server with your key:

claude mcp add --transport http aistrail https://api.aistrail.com/mcp \
  --header "Authorization: Bearer $AIS_TRAIL_KEY"

Then type /mcp in Claude Code to check that aistrail is connected. In other MCP clients, add a remote (Streamable HTTP) server with the same URL and header. The key is saved in your client's configuration, so give the assistant a key of its own that you can revoke separately (see Create an API key).

To use only the tools that need no key, leave out the header. Clients that cannot add a header, such as hosted connectors that only offer OAuth, can use the tools without a key only; the archive tools then answer that they need a key.

Example questions

Ask in plain words; the assistant picks the tools. For example:

"Which ships called at Rotterdam last week?" find_port gives the port id, then port_calls lists the arrivals and departures (API key).
"Which tankers are in the Strait of Gibraltar right now?" vessels_in_area with ship_type tanker (no key).
"Find the ship MYSTAR and show where it sailed three days ago." search_vessels finds the ship, then vessel_track reads its track from the archive (API key).

Tools

All tools are read-only. Positions are what ships broadcast, times are UTC, results with ship data name the sources to credit in attribution, and the not-for-navigation notice applies to every answer.

Tool	Key	What it answers
`search_vessels`	Not needed	Ships by name, MMSI or IMO (`query`, 3 to 100 characters; `limit` up to 20): live ships first, then ships out of range with their last known position (up to 7 days).
`get_vessel`	Not needed	One ship by `mmsi`: identity (with the flag from the MMSI and an estimated deadweight and size class), last position, speed, course, heading, navigational status, destination and ETA, how long ago it was heard and its track over the last 40 minutes.
`vessels_in_area`	Not needed	Ships heard in the last hour inside a box of up to 5° on each side, largest first (`limit` up to 100, optional `ship_type`).
`vessels_near`	Not needed	Ships heard in the last hour within `radius_nm` (up to 50 nautical miles) of a point or of another ship, nearest first (`limit` up to 50).
`data_status`	Not needed	How many ships are live and known from the last 7 days, the history archive per source with its `available_until`, and the service status with its reasons.
`find_port`	Not needed	Ports by name, UN/LOCODE or country code from the World Port Index and UN/LOCODE (`query`, `country`, `locode`; `limit` up to 20): id (for `port_calls`), name, country, UN/LOCODE, position, harbor size and port area radius.
`vessel_track`	Required	Where a ship (`mmsi`) has been between `from` and `to`, from the archive: `raw` up to 24 hours, `1m` (default) up to 7 days, `1h` up to 366 days, at most 200 points per call.
`vessel_port_calls`	Required	Port calls of a ship (`mmsi` or `imo`) between `from` and `to`, up to 366 days: port, arrival, departure, draught and cargo estimate, at most 100 port calls per call.
`port_calls`	Required	Ships that called at a port (`port_id` from `find_port`) between `from` and `to`, up to 366 days, with `event` any, arrival or departure, at most 100 port calls per call.

API key, credits and plans

The tools that need no key answer from the same live picture as the free live map and use no credits. find_port reads the port reference, not AIS data.

vessel_track calls /v1/vessels/{mmsi}/track with your key, so your plan's history depth, sources, credits (1 per vessel-day, as on the track endpoint), rate limit and 24-hour delay on recent data (none on Pro and Business, which include live data) apply exactly as there. vessel_port_calls and port_calls call the port call endpoints the same way and use 1 credit per port call returned. There is no second set of rules for MCP: see Plan limits and Credits.

When the API refuses a call, for example with 402 Out of credits or 403 History limit, the tool result has isError and gives the API's status and detail.

Private vessels

Pleasure craft, sailing vessels and Class B transponders without a valid IMO number are private vessels. The tools never list them or look them up one by one, on any plan: area and nearby results only count them in private_vessels, and a search, a ship lookup or a nearby search centred on one answers as for a ship never seen. MMSIs withdrawn at their owner's request appear nowhere. vessel_track follows the rules of the track endpoint (see Private vessels in the API reference).

Limits and errors

Rate limit. Tool calls are limited to 10 per second per IP address (for IPv6, per /64 network) without a key and 20 per second per account with a valid one. When the server is busy, search, area, nearby and status calls may be asked to retry in a second. Connecting, listing the tools and ping are not limited.
Refused and failed calls. A refused or failed call comes back as a tool result with isError and a message that says what to do, not as a protocol error.
Live data. While the live view is starting, for example after a restart, the live tools ask you to retry in a few seconds. When it is not current, their results show the last known positions with live_stale_s and live_note.
Requests. The server answers POST with Content-Type: application/json only (other types get 415). Requests from browsers (with an Origin header) get 403, and bodies over 64 KB get 413. JSON-RPC batches are accepted only from 2025-03-26 clients, at most 20 messages each.

Found a mistake, or something unclear? Suggest an edit and we will fix the page.