How to Use the VesselAPI MCP in Pydantic AI

Q: What happens if I use VesselAPI for port listing in Pydantic AI?

You call listmaritimeports, and the resulting list is typed. Your Pydantic model ensures that every entry has a required 'port name' string, preventing unusable data.

Ensure data correctness when tracking vessels using Pydantic AI's type validation layer.

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 Pydantic AI

Create your Vinkius account to connect VesselAPI to Pydantic 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 Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Validate Vessel Schedules and Ports

Use `get_vessel_schedules` to fetch upcoming port calls. When the API returns this data, your agent validates it against a Pydantic model, ensuring every date field is correct. This prevents silent failures; if the schedule format breaks, the agent throws a loud validation error immediately.

Confirm Vessel Status and Location

The `check_api_status` tool confirms operational status. Furthermore, when you call `get_vessel_position`, your agent validates that latitude and longitude are present and correctly typed. This rigor means your agent only proceeds with location data it knows is perfectly structured.

Search Vessels by Name or IMO Number

When running `search_vessels` or `get_vessel_details`, the raw JSON response is immediately validated. Your Pydantic model enforces that fields like 'IMO number' and 'Vessel name' exist. This guarantees type safety for all maritime data passing through your agent.

Setup guide

Set up VesselAPI MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "vesselapi-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to VesselAPI tools.",
)

result = await agent.run("List recent VesselAPI transactions")
print(result.output)

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 Pydantic AI

Every MCP tool response is validated at runtime against schemas you define. If `get_vessel_details` returns an unexpected field, the agent fails loudly instead of proceeding with corrupt data.

You call `list_maritime_ports`, and the resulting list is typed. Your Pydantic model ensures that every entry has a required 'port name' string, preventing unusable data.

The server touches structured maritime records, including vessel names, IMO numbers, and coordinates. Your agent enforces that these specific fields adhere to strict Python typing definitions.

Yes. You can first search for a vessel, get the IMO from that result, and then pass it to `get_vessel_position`. The type validation runs on both results sequentially.

It's extremely reliable because of the validation layer. You get immediate feedback if any tool, even `get_vessel_schedules`, returns malformed data.

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