AI assistants

Pelyr runs a remote MCP server at https://api.pelyr.com/mcp. Connect it to an AI assistant and the assistant can look up vessels, positions and tracks while it answers you — with your key, your quota and your rate limits.

The server is a read-only view of the HTTPS API: ten tools over the same ten endpoints, and nothing else. There is no write path and no live stream.

What you get

Tool	What it answers
`list_sources`	Which sources and licences are behind the data, and the attribution line to show as the licence requires
`find_vessels`	Every vessel in a bounding box right now, shortened and capped
`get_vessel`	One vessel by MMSI, full field set
`get_vessel_track`	The track of one vessel over a time range
`vessels_at_time`	Every vessel in a box at one instant from the current UTC day or the two before it; plans from Fleet up
`search_vessels`	Vessels by name, IMO or MMSI, ranked — also vessels that are not transmitting right now
`list_detection_areas`	The areas of sea that are searched for vessels in satellite images; plans from Fleet up
`list_detection_overflights`	The satellite overflights of one area, newest first, with the AIS coverage and the counts of what was found; plans from Fleet up
`get_detection_overflight`	One overflight: the vessels detected in the image, their stored AIS facts and the STS pairs; plans from Fleet up
`list_sts_finds`	STS finds across the areas, newest first, with reasons and AIS partners — filtered and paged; plans from Fleet up

Three resources come with them: pelyr://licence (licence and attribution), pelyr://limits (the current limits), and pelyr://fields (what nav_status, type, plausibility, match and the other coded fields mean). An assistant can read them without spending a request.

Before you connect

Create your Pelyr account first. Signing in during a connector flow works for an account that already exists, and so does a first sign-in through GitHub — either way you land back at the assistant. Registering with an email address instead takes you into the portal, not back to the assistant; if that happens, the parked request expires after fifteen minutes — start the connection again from the assistant.

Then pick your route:

Claude — Claude.ai, Claude Desktop, Claude Code
ChatGPT — developer mode connector
Developer tools — Cursor, VS Code, Gemini CLI, Windsurf
Your own agents — Claude API, managed agents, OpenAI Responses

One key per client

Claude.ai and ChatGPT sign in over OAuth: you approve the connection once on a Pelyr page, and Pelyr mints one key for that client. It appears in your key list under AI assistants, labelled with the client's host — claude.ai, chatgpt.com — and carries the https capability. It does not count toward your key limit.

Revoke it there and the connector is cut off at once: its next tool call that reads vessel data is refused, and the assistant will offer to sign in again. Approving again mints a fresh key. There is no separate "connected apps" screen: the key list is the list.

Developer tools and your own code skip all of that and send a pk_ key you created yourself in the Authorization header. Same key, same budgets as the HTTPS API.

Limits

Rate limits are counted per key in a sliding 60-second window — the same three independent budgets as on the HTTPS API. Exhausting one does not affect the others, and everything else that uses the same key counts into the same windows: your own HTTPS calls and the assistant's tool calls share them. A connector and a pk_ key you use yourself never share a budget — each has its own key.

Tools	Limit
`find_vessels`, `get_vessel`, `vessels_at_time`, `search_vessels`, `list_detection_areas`, `list_detection_overflights`, `get_detection_overflight`, `list_sts_finds`	the per-minute limit of your plan; Free plan: 2 per minute per API key
`get_vessel_track`	the per-minute limit of your plan; Free plan: 2 per minute per API key
`list_sources`	1 request / minute

An agent asks several questions per turn, so these are tighter here than they look on the HTTPS API. Over the limit, the tool answers with rate_limited and the number of seconds to wait — the connection stays up, the assistant can try again. If your workload needs a higher limit, write to hello@pelyr.com.

Answer sizes are capped so that a result still fits into a model's context:

find_vessels and vessels_at_time return 100 vessels by default and 500 at most (max). A box with more vessels in it comes back flagged, not silently shortened.
get_vessel_track returns at most 500 points; a longer track is thinned out evenly and flagged with downsampled.
find_vessels and vessels_at_time return a shortened field set. The full one — draught, ETA, dimensions, plausibility — is what get_vessel is for.
search_vessels returns 10 candidates by default and 25 at most (max). A name without an exact match returns the closest names, marked as approximate — candidates to check, not an identification.
list_detection_overflights returns 100 overflights by default and 500 at most (max). get_detection_overflight returns 100 detections by default and 500 at most (max), but keeps every detection of an STS pair, so count can exceed max; truncated_by_max and total_detections say what was left out.
list_sts_finds returns pages of 50 finds by default and 200 at most (limit); page on with cursor until next_cursor is null.

Licence and attribution

Every answer that carries vessel data — find_vessels, get_vessel, get_vessel_track, vessels_at_time, search_vessels, get_detection_overflight, list_sts_finds — carries its own attribution block for the licences it used, and the line

AIS data is not for navigation or safety of life at sea.

list_sources carries the same notice, and puts the attribution on each entry of its sources list instead of a single block, one entry per licence. list_detection_areas and list_detection_overflights carry the notice too, but no AIS vessel facts, so their attribution is empty.

The attribution is not decoration. Third-party sources always require their credit wherever the data is shown; the Pelyr Data Licence 2.0 requires the Pelyr credit for data that may be used for non-commercial purposes only (section 3.1 of the licence). An answer an assistant writes from the data is such a place. The tool descriptions ask the model for it; a model is not a guarantee, so if your assistant keeps dropping the line, put it in your system prompt.

Vessel positions are reported by the vessels themselves and are not verified. They are not a navigational aid, and an AI summary of them is even less of one.