How to Use the Correios (Brazil) MCP in Mastra AI

Q: How do I handle Correios (Brazil) API failures inside Mastra AI?

Use Mastra AI's workflow engine to wrap trackobject or calculatepricedeadline in a retry block. If the Correios (Brazil) server returns a timeout, Mastra automatically retries the call using exponential backoff.

Q: Can I build multi-step shipping pipelines with Correios (Brazil) and Mastra AI?

Yes, you can chain lookupcep to verify an address, and then immediately trigger calculatepricedeadline in a single Mastra AI workflow. This lets you automate complex Brazilian shipping calculations.

Run complex, multi-step Brazilian logistics workflows with Mastra AI and this Correios (Brazil) integration.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Correios (Brazil) MCP to Mastra AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automate postal code validation within Mastra workflows

The `lookup_cep` tool retrieves full Brazilian address details using only a postal code. Within a Mastra AI workflow, this tool acts as an automated validation step that runs before any package label is generated. If the address lookup fails, Mastra's built-in retry logic kicks in to handle API rate limits. You can build a conditional branch that flags invalid CEPs and alerts your support team automatically.

Track Correios packages with automatic retry loops

The `track_object` tool fetches the current transit status of any Brazilian package. Mastra AI schedules this tool to run at set intervals, tracking packages from dispatch to final delivery without manual intervention. When the Correios API experiences its typical afternoon slowdowns, Mastra's exponential backoff ensures your background workers don't crash. You get reliable delivery updates fed straight into your internal databases.

Manage shipping contracts with this Mastra AI MCP Server

The `get_contract_status` tool checks the validity and active services of your Correios corporate account. Your Mastra AI agent runs this check to verify that your account has the correct permissions before attempting to calculate bulk shipping rates. This MCP Server handles the complex soap-to-json translation behind the scenes. Your agent simply receives a clean boolean status, allowing your logistics pipeline to make immediate routing decisions.

Setup guide

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

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

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

Use Mastra AI's workflow engine to wrap `track_object` or `calculate_price_deadline` in a retry block. If the Correios (Brazil) server returns a timeout, Mastra automatically retries the call using exponential backoff.

Yes, you can chain `lookup_cep` to verify an address, and then immediately trigger `calculate_price_deadline` in a single Mastra AI workflow. This lets you automate complex Brazilian shipping calculations.

You configure your contract credentials once inside Vinkius. The Mastra AI client then connects to the hosted MCP Server using a single secure token, removing the need to manage SOAP credentials in your application code.

Yes, you can use Mastra's tool approval feature. When your Mastra MCP client calls `calculate_price_deadline` or checks contract details, Mastra pauses the workflow until a manager approves the calculated cost.

All corporate contract tokens and pricing queries run inside isolated V8 sandboxes. Vinkius hosts this MCP Server on a zero-trust model, ensuring your shipping rates and contract statuses are never cached or exposed.

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