How to Use the DHL MCP in Pydantic AI

Q: How does Pydantic AI validate DHL API responses?

The framework intercepts the JSON returned by tools like getrates or trackshipment and validates them against strict Pydantic models. This ensures your MCP server data is always clean and matches your Python types.

Q: Can I use Pydantic AI to catch invalid DHL addresses?

Yes. By executing validateaddress through your toolset, the agent receives a standardized address format from the MCP server. Pydantic AI ensures this response conforms to your application's expected address schema before you write it to your database.

Q: How do I handle DHL shipment creation errors in Pydantic AI?

If createshipment fails, Pydantic AI raises a validation error that you can catch using standard Python try-except blocks. This keeps your shipping database clean and prevents bad labels from printing.

Build type-safe logistics pipelines with Pydantic AI to validate DHL addresses, rates, and shipping labels at runtime.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect DHL MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-Safe DHL Shipments with Pydantic AI

`create_shipment` generates DHL shipping labels while Pydantic AI validates the payload format at runtime. When you use Pydantic AI, every response from the DHL tool is strictly validated against Python type models, preventing corrupted shipping labels from entering your warehouse queue. This type-safe architecture ensures that DHL tracking numbers and label URLs are formatted correctly before your system processes them via the MCP server. You get absolute runtime guarantees that your logistics data is clean and actionable.

Strict Address Validation and Rate Queries

`validate_address` cleans up customer input before your Pydantic AI system books a DHL package. Pydantic AI validates the standardized DHL address output against your internal schemas to prevent shipping typos before you print a label. When quoting prices, the Pydantic AI agent calls `get_rates` to pull live DHL shipping costs safely. Because the framework enforces strict validation, your application can parse these rates without worrying about missing fields crashing your checkout flow.

Reliable Tracking and Customs Documentation

`track_shipment` returns live DHL status updates and estimated delivery dates directly to your Pydantic AI agent. Pydantic AI ensures the 10-digit DHL tracking number and checkpoint data conform to your application's data models. For international logistics, the Pydantic AI agent calls `get_proforma_invoice` to generate DHL customs documents. The structured output allows Pydantic AI to safely store the DHL invoice data without fear of schema drift.

Setup guide

Set up DHL 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": {
        "dhl-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

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

result = await agent.run("List recent DHL 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 DHL. 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 DHL 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 DHL MCP in Pydantic AI

The framework intercepts the JSON returned by tools like `get_rates` or `track_shipment` and validates them against strict Pydantic models. This ensures your MCP server data is always clean and matches your Python types.

Yes. By executing `validate_address` through your toolset, the agent receives a standardized address format from the MCP server. Pydantic AI ensures this response conforms to your application's expected address schema before you write it to your database.

If `create_shipment` fails, Pydantic AI raises a validation error that you can catch using standard Python try-except blocks. This keeps your shipping database clean and prevents bad labels from printing.

Yes, the MCP server runs externally and connects via Streamable HTTP or SSE transports. You configure the `MCPToolset` with the Vinkius endpoint URL to expose the tools to your agent.

Vinkius handles all authentication via a single-token endpoint, meaning your DHL credentials never touch the client code. Your tracking numbers and customs invoice details are processed entirely in memory inside an ephemeral sandbox, leaving no persistent footprint.

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