Query guide

https://api.vesselmcp.com is for applications, and https://mcp.vesselmcp.com is for agents. They provide the same read-only queries: retrieve vessel identity by IMO, or retrieve recent ports by IMO. Authentication and rate limits are separate; neither service accepts the other service's key. See Domains for each hostname's role.

The vesselmcp.com public website contains locally retained snapshots and does not use either programmatic interface. Programmatic results may differ from the record date and field scope displayed on public pages.

IMO only

Layer	Identity	Ports
REST	GET /v1/vessels/{imo}	GET /v1/vessels/{imo}/recent-ports
MCP	vesselmcp_get_vessel	vesselmcp_get_recent_ports

• An IMO must have seven digits, pass the checksum, and cannot be 0000000.
• There is no vessel-name search, pagination, retired aggregate endpoint, or alias.
• A successful identity response has no port fields; a successful port response has no optional identity fields.
• When both are needed, make both calls. Each counts against that service's IP and key-ID limits; cached hits are not exempt.

Checksum: multiply the first six digits by 7, 6, 5, 4, 3, and 2 in order. The sum of the products modulo 10 must equal the seventh digit.

Identity

A successful object permits only imo and the optional name, flag, vesselType, callsign, and mmsi. Every success must include fetchedAt.

REST wraps it as { "data": { "vessel": ... } }. When a vessel is genuinely not found, REST returns 404 VESSEL_NOT_FOUND and the MCP tool returns the isError text Vessel not found.. Any other identity failure is a query failure, not a “not found” result.

Ports

A successful result has exactly three fields: imo, recentPorts, and fetchedAt. It contains at most 10 entries; the same port may appear more than once, and the list is not guaranteed to be a complete history. An empty array [] is still a valid success and must include fetchedAt.

A port-query failure (timeout, unavailability, invalid data, or busy state, for example) is always a query failure: REST returns 502 BACKEND_UNAVAILABLE and MCP returns a general isError. It must not become an empty array or “vessel not found.” A known IMO may query ports directly without first querying identity.

Each port entry:

Field	Rule
id	Required; 1–64 ASCII letters, digits, underscores, or hyphens
portName	Required; 1–120 UTF-16 code units, no leading or trailing whitespace, and no control characters
portId	Optional; same rule as id
unlocode	Optional; two uppercase letters followed by three uppercase letters or digits
coordinates	Optional; [longitude, latitude], longitude in [-180,180] and latitude in [-90,90]
arrival / departure	Optional UTC YYYY-MM-DDTHH:mm:ss.sssZ; when both exist, departure is not earlier than arrival
minutesOfStay	Optional finite non-negative number
status	Optional; only arrived, departed, or inPort

Entries are deduplicated by id, not by port name. There are no sorting or pagination parameters.

fetchedAt

This is the time a successful identity or port collection completed. It is not a port-event time and does not promise real-time data. The format is exactly the 24-character YYYY-MM-DDTHH:mm:ss.sssZ. Identity and ports do not share timestamps. A cached response preserves its original time.

Authentication

Service	Bearer format
REST	vmcp_api_v1_<key-id>_<secret>
MCP	vmcp_mcp_v1_<key-id>_<secret>

Apply from the homepage: enter your email and select API or MCP. The separate app.vesselmcp.com service sends a verification link valid for 30 minutes. Open it and confirm your email to receive only the selected service's key, valid for 90 days UTC, by email. Each service rejects keys issued for the other service. Raw secrets do not appear in rate-limit counters.

Allow at least one hour between applications. Each email can hold one unexpired key per service; existing keys are not replaced or resent. Key delivery is attempted once. If issuance starts but email delivery cannot be confirmed, another key cannot be issued automatically before that 90-day validity ends. Contact support if no key arrives; never include a key or verification link in your message. This documentation site does not issue keys. Application availability depends on the separate service being enabled.