How to Use the Correios API (REST) MCP in Mastra AI

Build resilient Brazilian logistics workflows using Mastra AI to track and price shipments automatically.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Correios API (REST) MCP to Mastra AI

Create your Vinkius account to connect Correios API (REST) 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 Correios API (REST) with Mastra AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automated shipping retries with Mastra AI

Brazilian postal APIs can be finicky during peak hours. When you register this MCP Server with Mastra, you can build workflows that catch rate-limiting errors instantly. If `calculate_price_deadline` fails, Mastra automatically retries with exponential backoff. You don't have to write custom loop logic or error handlers. The framework manages the state machine, ensuring your backend gets accurate shipping quotes even when the external network is shaky.

Conditional routing for shipping exceptions

Package delays happen, but your system should respond immediately. Use `track_object` inside a Mastra workflow to monitor critical shipments. If the status changes to an alert state, the workflow triggers a specific branch to notify your support team. This lets you build autonomous logistics handlers. Your agent checks the status, evaluates the transit step, and decides whether to file a claim or wait.

Human-in-the-loop approval gates

Sometimes you need a human eye before committing to a costly shipping option. You can set up Mastra to require manual approval before executing `calculate_price_deadline` for high-value orders. The system pauses the workflow and waits for your signal. It gives you complete control over automated shipping decisions. Your agents do the research, and you make the final call.

Setup guide

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

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

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

You initialize the Mastra MCP client with your Vinkius server URL. Once connected, use the listTools method to register the Correios tools. Your Mastra agents can then call them dynamically during execution.

Yes, Mastra has built-in workflow controls to handle API limits. If the Brazilian postal server returns a temporary error, the MCP workflow engine retries the call. This keeps your logistics pipeline running without manual intervention.

It does. You can configure Mastra to halt execution before calling the shipping tools. This is perfect when you want to review calculated prices before confirming an order.

The system supports both SSE and Streamable HTTP transports. Mastra automatically detects the optimal connection type when you pass the Vinkius MCP URL. You don't need to write any custom networking code.

Your shipping addresses and tracking numbers are processed in memory and never persisted. The Vinkius gateway handles the handshake securely using isolated runtime environments. Your customer logistics data remains completely confidential.

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