How to Use the BrasilAPI MCP in Mastra AI

Q: Does Mastra AI support human-in-the-loop validation for BrasilAPI CNPJ checks?

Yes, you can use the requireToolApproval option in Mastra AI when calling getcnpjdetails. This pauses the workflow so a team member can verify the Brazilian corporate registry data before the agent continues.

Q: How secure is the CNPJ and CEP data handled by Mastra AI workflows?

Every execution of getcnpjdetails and getcepdetails is isolated inside an ephemeral V8 sandbox. Your Mastra workflows receive the validated Brazilian registry data over encrypted SSE connections, ensuring no sensitive address records are leaked.

Run automated workflows with Mastra AI to verify Brazilian CNPJ, CEP, and bank details with built-in retries.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect BrasilAPI MCP to Mastra AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Validate bank codes with Mastra AI workflows

Using `list_brazilian_banks` retrieves active clearing numbers and registration details for all financial institutions in Brazil directly into your Mastra AI agent. Your Mastra AI workflows use this bank data to build automated payout validation checks before executing transfers. If a bank lookup fails, Mastra's workflow engine triggers an automatic retry to fetch the Brazilian bank code again. This keeps your payment pipelines moving without manual intervention as your Mastra agent handles the Brazilian bank lookup exception silently.

Conditional shipping routes via BrasilAPI MCP Server

Calling `get_cep_details` extracts precise geographic coordinates and state codes for any Brazilian address directly into your Mastra AI workflows. Mastra AI agents use this CEP data to execute conditional branching logic for localized logistics in Brazil. Your Mastra agent queries the CEP, evaluates the state via `list_brazilian_states`, and routes the delivery order to the nearest regional distribution hub. By defining the routing logic in Mastra AI, the MCP tools supply the raw Brazilian state data to direct your shipments.

Automated CNPJ background checks in Mastra AI

Executing `get_cnpj_details` fetches the legal name, status, and capital structure of Brazilian businesses for your Mastra AI agent. Mastra AI agents run this CNPJ tool as a background step in your customer onboarding workflows. You can require human-in-the-loop approval before processing high-risk Brazilian corporate accounts through Mastra AI. Once paused, the Mastra workflow halts, notifies your admin, and resumes only after the CNPJ verification data is approved.

Setup guide

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

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

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

Instantiate the client using the Vinkius URL, then spread the `listTools()` output directly into your Mastra agent's tool configuration. The agent automatically gets access to `get_cep_details` and `get_cnpj_details` for its decision loops.

Yes, you can use the `requireToolApproval` option in Mastra AI when calling `get_cnpj_details`. This pauses the workflow so a team member can verify the Brazilian corporate registry data before the agent continues.

Yes, Mastra's workflow engine manages rate limits by wrapping the `get_fipe_vehicle_price` tool in retry blocks. If the BrasilAPI endpoint returns a rate limit error, the agent backs off and retries automatically.

Mastra AI connects using the standard HTTP transport protocol provided by Vinkius. You just pass your unique Vinkius endpoint URL to the Mastra MCP client constructor, and it discovers all six Brazilian data tools instantly.

Every execution of `get_cnpj_details` and `get_cep_details` is isolated inside an ephemeral V8 sandbox. Your Mastra workflows receive the validated Brazilian registry data over encrypted SSE connections, ensuring no sensitive address records are leaked.

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