# JSONCargo Maritime MCP > JSONCargo Maritime lets your AI agent handle all global shipping data requests. Search vessels by name or IMO number, audit current voyage status, and retrieve detailed port metadata without needing to log into any separate maritime portal. It turns complex, multi-site logistics research into a single conversation with your agent. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** maritime-data, vessel-tracking, logistics-api, voyage-monitoring, port-data, real-time-tracking ## Description Tracking ships and auditing trade routes used to be a manual nightmare. You'd have to jump between multiple global shipping portals, running different searches just to piece together a vessel’s history or current location. Now, you connect JSONCargo Maritime to your agent, and it handles the whole workflow. Your AI client acts like a dedicated maritime consultant, retrieving real-time data on thousands of ships and ports instantly. You can ask your agent to audit a voyage's status or pull up detailed metadata for any port worldwide. This capability is hosted right here on Vinkius, meaning you connect once from any MCP-compatible client and get access to this entire maritime dataset. Whether you’re running supply chain research or just monitoring regional trade constraints, the data stays verified and precise. ## Tools ### check_api_status Verifies if the JSONCargo data service is currently operational and accessible. ### get_current_voyage_details Retrieves all tracking metadata for a vessel that is actively sailing on its route. ### list_maritime_ports Provides a searchable list of every global port registered in the database, along with their location codes. ### search_maritime_vessels Locates specific vessels by searching using either their official IMO number or known name. ## Prompt Examples **Prompt:** ``` Search for vessel 'Ever Given' using JSONCargo. ``` **Response:** ``` I've retrieved the details for Ever Given! It is a Container Ship with IMO number 9811000. Would you like the current voyage metadata or the vessel's flag information? ``` **Prompt:** ``` What is the current voyage status for vessel ID 'VES-123'? ``` **Response:** ``` I've identified the current voyage for VES-123! It is currently identified as 'En Route' from Singapore to Rotterdam. The current position was updated [Time] ago. I can provide the full track metadata if you'd like. ``` **Prompt:** ``` List all maritime ports in 'Netherlands'. ``` **Response:** ``` I've retrieved the port catalog for the Netherlands! Notable entries include Rotterdam (NLRTM) and Amsterdam (NLAMS). I can provide the full LOCODE and terminal metadata for each of these sites. ``` ## Capabilities ### Search for specific vessels Find records on thousands of ships using either their name or official IMO number. ### Audit current vessel routes Retrieve the full metadata and status for a ship currently in transit. ### List global port records Access an official catalog of ports, including their unique location codes (LOCODEs). ### Monitor service health Confirm that the underlying JSONCargo data source is operational and running. ## Use Cases ### A shipment is delayed; I need its current location. I'm worried about the cargo. My agent needs to know where it is right now. I ask it, 'What's the status of vessel ID ABC-123?' The agent uses `get_current_voyage_details` and gives me the exact route and last updated position. ### I need to check if a port is valid for my new route. The planner needs to build a new trade corridor. I ask the agent to list all ports in Singapore. It runs `list_maritime_ports` and returns the full, verifiable LOCODE catalog for me to use. ### A competitor's ship pops up in my research. I need quick data on a vessel I just heard about. I ask the agent to find it by its name. It uses `search_maritime_vessels` and gives me the full metadata, including its flag type. ### We are running a major audit of our whole network. I need to confirm that all my data feeds work before I run reports. I ask the agent to check the service health. It runs `check_api_status` and confirms everything is green, so I know the report will be accurate. ## Benefits - Avoid manual lookups: Instead of searching multiple sites for a ship's details, you simply ask your agent to use `search_maritime_vessels` by name or IMO number. It gets the metadata directly. - Know where ships are right now: Use `get_current_voyage_details` to pull real-time status and position data for any vessel without needing a dedicated tracking dashboard. - Control your routes with certainty: The `list_maritime_ports` tool gives you access to the full catalog of global ports, letting you verify LOCODEs before planning anything. - Build reliable workflows: Running `check_api_status` first confirms that all the data sources are online and ready for deep-dive research. No guesswork involved. - Faster reporting: You can combine tools like searching vessels and listing ports to build complex reports in one conversational turn, saving hours of copy/pasting. ## How It Works The bottom line is, once configured, your agent uses this MCP as a single source for all global shipping data. 1. Subscribe to this MCP and provide your unique JSONCargo API key. 2. Connect your preferred AI client (like Claude or Cursor) to Vinkius using the credentials. 3. Tell your agent what you need—for instance, 'What is the status of vessel X?'—and it runs the necessary queries. ## Frequently Asked Questions **How do I check if the JSONCargo Maritime MCP connection is working?** Run the `check_api_status` tool. This immediately confirms if the data source is operational, which you should always run as your first step in any audit workflow. **What information can I get using search_maritime_vessels?** This tool finds ships by name or IMO number and retrieves key metadata like the vessel type and flag. It's perfect for initial identification before tracking its movement. **Can list_maritime_ports help me with a route plan?** Yes, it gives you the full global catalog of ports and their specific LOCODEs. You use these codes to verify that your planned route touches established, verifiable terminals. **Does get_current_voyage_details give me historical data?** No, this tool focuses on the vessel's current status and position—the active voyage details. If you need historical logs, your agent can combine this with other sources. **How do I handle rate limits when calling `get_current_voyage_details`?** The MCP will return a specific HTTP status code indicating throttling. Your agent must implement exponential backoff logic; wait longer after each failed attempt to prevent service interruption. **Does `search_maritime_vessels` require the full IMO number, or can I use partial names?** You do not need a perfect match. While exact IMO numbers yield the best results, you can search using vessel names or partial identifiers; the system cross-references available metadata. **Can `list_maritime_ports` filter results by specific countries or regions?** Yes, the tool accepts regional parameters. You must pass a country code (e.g., 'US' for United States) in the input to narrow down the global port list effectively. **What should I consider when running multiple searches using `search_maritime_vessels`?** The system is built for high volume, but sustained, rapid querying can hit rate limits. It's best practice to space out bulk requests or utilize batch processing within your agent workflow. **How do I find my JSONCargo API Key?** Log in to your [**JSONCargo account**](https://api.jsoncargo.com/), navigate to your dashboard, and you will find your API Key in the 'Access Tokens' section. Copy and paste it below. **What vessel identifiers are supported?** The API supports searching by vessel name, IMO number, and unique JSONCargo identifiers. **Does it support real-time positions?** Yes. The `get_current_voyage_details` tool retrieves the most recent position and status metadata for active vessels.