How to Use the VesselAPI MCP in Mastra AI

Q: How do I use VesselAPI in a complex flow with Mastra AI?

You define the entire sequence of tools, like calling searchvessels followed by getvesseldetails. The Mastra AI framework manages the state between calls. It handles the transition automatically.

Q: What if I need to list all ports using VesselAPI in Mastra AI?

You just add listmaritimeports as a step. If that tool is available, your workflow executes it and passes the resulting port list to the next step for validation or further use.

Q: Can I control execution flow with VesselAPI using Mastra AI?

Yes. You build conditional branches: 'If getvesselschedules shows no calls in June, then notify admin.' This gives you granular control over the entire automation pipeline.

Build resilient maritime tracking workflows with Mastra AI using VesselAPI.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect VesselAPI MCP to Mastra AI

Create your Vinkius account to connect VesselAPI to Mastra AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup VesselAPI with Mastra AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Define vessel search and lookup steps.

Start by calling `search_vessels` to narrow down a target ship. If the initial results are too broad, your workflow can then automatically branch and call `get_vessel_details` using an IMO number found in the list. This conditional logic handles complex lookups better than simple scripts. The Mastra AI framework ensures that if the detail lookup fails, it retries with a different search criteria.

Automate position updates and status checks.

You can build a loop that calls `get_vessel_position` every few minutes. If the API call fails or returns no data, the built-in workflow engine will automatically retry with exponential backoff. This makes your MCP Server integration reliable for production use. You don't have to write custom failure handling code.

Manage port schedules and availability.

Build a sequence that first calls `list_maritime_ports` to validate the region, then uses `get_vessel_schedules` to get potential dates. If the schedule is outside business hours, your workflow can notify an admin instead of failing. This multi-step process gives you full control over how operational data flows through your application.

Setup guide

Set up VesselAPI MCP in Mastra AI

Prerequisites

Node.js 18+ and a TypeScript project
@mastra/mcp + @mastra/core packages
Active Vinkius subscription with a valid endpoint token

1

Install dependencies
Run npm install @mastra/mcp @mastra/core plus your preferred model provider (e.g. @ai-sdk/openai).
2

Configure the MCPClient
Create an MCPClient with your Vinkius endpoint as a URL object. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com.
3

Discover and inject tools
Call mcpClient.listTools() and spread the result into your agent's tools object. All VesselAPI tools become native Mastra tools.
4

Run with any model
Swap openai("gpt-4o") for any AI SDK-compatible provider. Call agent.generate() and the agent routes tool calls through MCP automatically.

agent.ts

import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

const mcpClient = new MCPClient({
  id: "vesselapi-mcp-client",
  servers: {
    "vesselapi-mcp": {
      url: new URL(
        "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
      ),
    },
  },
});

const agent = new Agent({
  name: "VesselAPI Agent",
  model: openai("gpt-4o"),
  instructions: "You have access to VesselAPI tools.",
  tools: {
    ...(await mcpClient.listTools()),
  },
});

const result = await agent.generate(
  "List recent VesselAPI transactions"
);
console.log(result.text);

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by VesselAPI. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect VesselAPI now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about VesselAPI MCP in Mastra AI

You define the entire sequence of tools, like calling `search_vessels` followed by `get_vessel_details`. The Mastra AI framework manages the state between calls. It handles the transition automatically.

Absolutely. You set up automatic retries with exponential backoff for any tool, including `get_vessel_position`. If the first attempt fails, it waits and tries again until successful or until the max attempts are hit.

You just add `list_maritime_ports` as a step. If that tool is available, your workflow executes it and passes the resulting port list to the next step for validation or further use.

Yes. You build conditional branches: 'If `get_vessel_schedules` shows no calls in June, then notify admin.' This gives you granular control over the entire automation pipeline.

The server touches AIS positions, IMO numbers, and schedules. Since this is an automated workflow, ensure your process logs only capture necessary operational metadata and never raw personal identifiers.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript