How to Use the Shippo MCP in Mastra AI

Q: How does Mastra AI handle rate checking using Shippo?

The workflow starts by calling createshipmentgetrates. If the rates endpoint fails, Mastra AI automatically retries the call with exponential backoff before failing over to a different carrier check.

Q: Can I list recent shipments using Shippo and Mastra AI?

Yes. You can use listrecentshipments as a pre-check step in your workflow. This lets you confirm the shipment history before attempting any new label purchases.

Q: What is the best way to list connected carriers with Shippo and Mastra AI?

Use listconnectedcarriers early in your process. This validates that all necessary carrier accounts are available, preventing a hard failure later when you try to purchase a label.

Q: Does the MCP Server support listing saved addresses for Shippo and Mastra AI?

Absolutely. listsavedaddresses pulls your stored address data into the workflow, so subsequent steps don't need to re-validate basic input information.

Build resilient shipping workflows that recover automatically using Mastra AI's state machine logic.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Shippo MCP to Mastra AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Multi-Step Rate & Label Workflow

You can start the process with `create_shipment_get_rates` to establish baseline costs. Then, you chain this into a label purchase by calling `purchase_shipping_label`. Mastra AI handles retries if the API call fails due to throttling. This means your complex workflow doesn't crash on the first error. It automatically backs off and tries again, making it reliable for production-grade logistics.

Address Validation & Cleanup

If a shipment fails due to an address issue, you can trigger `create_and_validate_address` within your workflow. Mastra AI uses this result to automatically correct the input for the next attempt. This guarantees that bad inputs don't stop your entire process; they just trigger a self-healing step.

Handling International Compliance

For cross-border shipments, you need more than just rates. Your workflow can first check `list_customs_declarations` and then use `list_customs_items` to gather all required paperwork data. Mastra AI ensures that if the customs check fails validation, it alerts an admin before proceeding with a label purchase.

Setup guide

Set up Shippo 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 Shippo 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: "shippo-mcp-client",
  servers: {
    "shippo-mcp": {
      url: new URL(
        "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
      ),
    },
  },
});

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

const result = await agent.generate(
  "List recent Shippo 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 Shippo. 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 Shippo 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 Shippo MCP in Mastra AI

The workflow starts by calling `create_shipment_get_rates`. If the rates endpoint fails, Mastra AI automatically retries the call with exponential backoff before failing over to a different carrier check.

Yes. You can use `list_recent_shipments` as a pre-check step in your workflow. This lets you confirm the shipment history before attempting any new label purchases.

Use `list_connected_carriers` early in your process. This validates that all necessary carrier accounts are available, preventing a hard failure later when you try to purchase a label.

Absolutely. `list_saved_addresses` pulls your stored address data into the workflow, so subsequent steps don't need to re-validate basic input information.

The system handles international customs item data. When retrieving `list_customs_items`, the MCP Server provides structured text describing the goods, ensuring your workflow only processes necessary compliance details.

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