How to Use the Correios API (REST) MCP in OpenAI Agents SDK

Run OpenAI Agents SDK with live Correios API data to track Brazilian packages and calculate shipping costs 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 OpenAI Agents SDK

Create your Vinkius account to connect Correios API (REST) to OpenAI Agents SDK 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 OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automate Brazilian shipping quotes in OpenAI Agents SDK

The `calculate_price_deadline` tool lets your Python agent query real-time shipping rates and delivery times from Correios. You feed the agent package dimensions and zip codes, and it directly calculates the cost without manual API coding. This setup runs inside your agent workflow with performance in mind. Setting cacheToolsList to true keeps these shipping queries fast during high-volume checkout simulations.

Track packages securely with built-in guardrails

The `track_object` tool pulls the exact shipping status of any Brazilian package directly into your agent runtime. Your OpenAI agent monitors the delivery pipeline and flags transit delays instantly. Guardrails in this SDK validate the tracking format before the tool fires. You prevent useless API calls to Correios by stopping invalid tracking codes at the SDK layer.

Handoff shipping exceptions to specialized agents

The `track_object` tool feeds raw Correios status updates into your multi-agent architecture. When a package gets stuck in customs, your routing agent detects the issue and hands the task to a support agent. Full tracing on your OpenAI dashboard shows you exactly when the MCP Server returned the delay. You debug routing bottlenecks by watching how agents pass Correios payloads back and forth.

Setup guide

Set up Correios API (REST) MCP in OpenAI Agents SDK

Prerequisites

Python 3.10+ installed
openai-agents package (pip install openai-agents)
Active Vinkius subscription with a valid endpoint token

1

Install the SDK

Run pip install openai-agents to install the OpenAI Agents SDK. The MCP integration is built-in — no extra dependencies needed.
2

Connect via SSE transport

Use MCPServerSse with your Vinkius endpoint URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. The SDK auto-discovers all Correios API (REST) tools at runtime.
3

Create your Agent

Pass the MCP to Agent(mcp_servers=[server]). The agent receives Correios API (REST) tools as native definitions — JSON schemas resolve automatically.
4

Run the agent

Call Runner.run(agent, prompt) to execute. The agent invokes the appropriate Correios API (REST) tools and returns structured results. Copy the full example on the right to get started.

agent.py

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerSse

async def main():
    async with MCPServerSse(
        url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    ) as server:
        agent = Agent(
            name="Correios API (REST) Agent",
            instructions="You have access to Correios API (REST) tools.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "List recent transactions")
        print(result.final_output)

asyncio.run(main())

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 OpenAI Agents SDK

Install the package and configure the HTTP MCP Server parameters with your Vinkius endpoint. Pass the server instance directly into your Agent constructor to let tools auto-discover.

Yes, the connection relies on an async context manager. You initiate the MCPServerStreamableHttp instance within an async block to handle concurrent shipping queries.

You control tool access by defining specific agent schemas in your Python code. If an agent only needs to check shipping rates, expose just the `calculate_price_deadline` tool.

Enabling tool list caching prevents the SDK from querying the MCP Server for tool schemas on every turn. Your agent fires the `calculate_price_deadline` tool instantly without network lag.

Vinkius runs the MCP Server in an isolated sandbox, meaning your tracking numbers and zip codes never persist on external disks. Your OpenAI agent processes the tracking payload in memory and discards it immediately after execution.

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