Vessels MCP: Track a Ship From an Agent

Port agents, husbandry teams, and ops engineers often need to confirm “where is my vessel right now?” and then share that position downstream to a TMS, PDA, or ETA workflow. By the end of this guide you’ll be able to track a ship from an agent’s MMSI using Vessels MCP in a browser or a single REST call, handle the JSON envelope safely, and integrate the result into your own systems.

What “track from an agent” means and when to use it

Agents typically exchange the vessel’s MMSI before arrival or departure. With that single identifier you can:

Open Vessels MCP and see the vessel’s latest reported position and related catalog context.
Call the REST Track endpoint to ingest the same data into your back end.

This keeps your workflows simple: one MMSI in, one tracking payload out, and the same X-API-Key across MCP and REST.

Quick start: credentials and environment

Get an API key and a trial in minutes:

Register for the Starter plan ($19.99/mo for 2,500 calls) with a 7‑day trial.
Copy your X-API-Key from your account.
Use the same key with MCP and REST:
- MCP catalog tools: point your client to MCP.
- REST base URL: https://vessels-api.com/api/V1

Two ways to track with the same key

Option A — Browser: Vessels MCP

Open the MCP catalog and use “track” to resolve a vessel’s latest reported position by MMSI. This is useful for quick checks, sharing screenshots, or validating that your key scopes are correct before you automate anything.

There is no separate “geofence” tool. If you need to know what’s around a location, use the MCP “nearby” tool with a latitude/longitude and a radius.

Option B — Code: REST Track endpoint

Call the Track endpoint with the vessel MMSI. Authentication uses the same X-API-Key header across both experiences. The response is a consistent envelope you can safely parse in your integration.

Track a vessel by MMSI via REST (curl and JSON)

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessel/track?mmsi=258785000"

The sample above uses the MMSI 258785000 for the vessel ZJ ATLANTIC, dated 2026-02-09. If you are tracking a different ship from your agent, replace the MMSI in the request with the one you were given. Live-position access is available on Professional+ and counts against a separate quota; plan your usage accordingly.

Understanding the JSON envelope

Every response follows the same envelope: {status, success, message, data}.

status: HTTP-like status code mirrored in the payload (string or number representation). Use it for logging and dashboards.
success: boolean indicating whether the server fulfilled the request. Always check this first.
message: human-readable context for errors or nonstandard outcomes (e.g., invalid MMSI, quota issues, or unavailable data).
data: the tracking payload for the MMSI you requested. For Track, this contains the vessel’s latest reported information. Treat fields inside data as your source of truth for coordinates, timing, and identifiers relevant to tracking. See the Documentation for each field’s definition and units.

Production tip: always branch on success. If success is false, rely on message for user feedback and do not attempt to read fields beneath data.

Python example: request, parse, and guard against missing fields

This example calls the same Track endpoint you saw above, reads the envelope, and demonstrates safe handling when success is false or fields are missing. Replace YOUR_API_KEY and the MMSI with your values.

import os
import sys
import json
import urllib.request

API_KEY = os.getenv("VESSELS_API_KEY", "YOUR_API_KEY")
MMSI = os.getenv("MMSI", "258785000")  # Replace with your agent-provided MMSI

url = f"https://vessels-api.com/api/V1/vessel/track?mmsi={MMSI}"
req = urllib.request.Request(url, headers={"X-API-Key": API_KEY})

try:
    with urllib.request.urlopen(req, timeout=15) as resp:
        raw = resp.read().decode("utf-8")
        payload = json.loads(raw)
except Exception as e:
    print(f"Request failed: {e}", file=sys.stderr)
    sys.exit(1)

# Envelope guards
success = payload.get("success", False)
status = payload.get("status")
message = payload.get("message", "")
data = payload.get("data")

if not success:
    print(f"Track failed (status={status}): {message}", file=sys.stderr)
    sys.exit(2)

# At this point, 'data' contains the tracking payload for the MMSI.
# Persist it as-is, or extract the fields your workflow needs.
# Use dict.get(...) to tolerate missing keys without crashing.
# For demonstration we print a compact summary safely:
def sget(d, k, default="-"):
    return d.get(k, default) if isinstance(d, dict) else default

summary = {
    "status": status,
    "success": success,
    # You can log 'message' even on success to track non-fatal notes
    "note": message or "",
    # Store the full data object for downstream consumers
    "data": data,
}
print(json.dumps(summary, ensure_ascii=False))

MCP vs REST: which should you use when?

Use MCP when you need quick human validation, ad-hoc lookups, or to provide non-technical teammates with self-service vessel tracking.
Use REST when you must automate tracking, build alerts, or synchronize position data into your own databases and dashboards.

Because both share the same X-API-Key, you can prototype interactively in the browser and then move the identical MMSI and interpretation logic into code, reducing mistakes.

Handling errors, missing values, and partial data

Real-world AIS and logistics feeds are bursty. Build these guards into your code:

Branch on success. On false, check message for a reason to display or log.
Use dict.get(...) or equivalent when reading fields in data so that missing or null values don’t crash your pipeline.
Cache the last known good tracking payload. If a subsequent call fails or yields an incomplete data object, you can fall back to your cached value and label it as “stale” in the UI.
Avoid tight polling loops. Respect your plan’s call budget and consolidate calls where possible. If multiple services need the same track, fetch once and fan out internally.

Units, timestamps, and timezones

Treat timestamps, coordinates, and other numeric values exactly as returned by the API. If you transform them, annotate your outputs with the conversion you apply. For precise field-by-field units and timezone semantics, consult the endpoint’s schema in the Documentation. When storing data long-term, preserve the raw values from data alongside any derived or human-formatted variants so you can reprocess without loss.

No geofence endpoint? Use “nearby” with lat/lon/radius

If your agent workflow includes “alert when my vessel enters a harbor box,” implement it with a nearby query against the area center and a chosen radius. You can simulate entry/exit by comparing successive responses over time. In MCP, the nearby tool is available directly; in code, keep your own list of centers and radii and poll at a cadence that matches your operational needs and call budget.

Access, quotas, and going live

Plans and trial: Starter is $19.99/mo for 2,500 calls and includes a 7‑day trial.
Live-position: Available on Professional+ and counted against a separate quota. If your use case requires frequent, current positions, factor this into your integration plan.
Single key, two surfaces: The X-API-Key you get after you Register works for both REST and MCP.

Launch checklist

Call Track by MMSI in a staging environment and log the full envelope.
Implement success and message handling paths; cache the last good data payload.
Add basic observability: call counts vs. plan limits, error-rate alerts, and response-time sampling.
If you need spatial alerts, wire up your nearby checks with documented lat/lon/radius and a reasonable polling interval.

Working with the ZJ ATLANTIC sample vs. your target ship

The sample in this article references MMSI 258785000 (ZJ ATLANTIC) from 2026-02-09 to make the Track workflow concrete. In your application, replace that MMSI with the one your agent shares. If you are unsure about the correct identifier, use the MCP search tool to locate the ship interactively, confirm its MMSI, and then move that MMSI into your REST calls.

FAQ

Do I have to use MMSI to call Track?
Yes. Provide the vessel’s MMSI to GET the Track result. If you only know a name, resolve its MMSI in MCP first and then call Track with that MMSI.

How should I poll the Track endpoint?
Batch your polling to match operational needs and your plan budget. Cache responses and avoid requesting the same MMSI repeatedly across multiple services—fetch once and distribute internally.

What happens when success is false?
Do not read fields under data. Use message to inform the user or logs about the cause, and retry based on your backoff policy.

Is live AIS included in Starter?
Live-position access is available on Professional+ and uses a separate quota. If your workflow depends on live positions, plan capacity accordingly.

Where do I find field units and timezones?
See the endpoint schema in the Documentation for authoritative definitions.

Track your next ship from an agent in minutes: get your key via Register, validate the flow in MCP, and wire the same call into your stack using the Documentation.