How to Use the NFe.io MCP in Mastra AI

Q: How do I handle failed NFe.io invoice generation in Mastra AI?

You map the issueserviceinvoice tool to a Mastra AI workflow step equipped with automatic retries. If the Brazilian government servers return a 500 error, Mastra backs off and retries the call automatically.

Q: Can Mastra AI automatically cancel a merchandise invoice in NFe.io?

Yes, by chaining cancelmerchandiseinvoice to your e-commerce return triggers inside a Mastra agent. The agent verifies the invoice details using getmerchandiseinvoice before executing the cancellation.

Q: How do I register new issuers using NFe.io and Mastra AI?

You register the createcompany tool within your Mastra AI agent's toolset. When your onboarding agent receives corporate details, it invokes the tool to register the issuer and immediately checks the result.

Automate complex Brazilian tax invoice workflows with Mastra AI and this production-ready MCP Server.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect NFe.io MCP to Mastra AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Multi-step tax workflows with Mastra AI

The `issue_service_invoice` tool integrates directly into your Mastra AI state machines to handle complex, multi-step billing pipelines. If a service invoice fails due to an incorrect municipal code, your workflow catches the error and executes an automatic correction step. Integrating this MCP Server lets you build reliable financial agents that don't fall over when external government webservers go offline. You define the retry logic once, and Mastra handles the execution details.

Automated merchandise returns and cancellations

The `cancel_merchandise_invoice` tool executes automatically when a Mastra AI workflow detects a payment chargeback or a return request. Your agent calls this tool to void the NF-e, then transitions to the next step in your supply chain pipeline. Combining this with `get_merchandise_invoice` lets your agent verify the cancellation state before initiating refunds. This automated check prevents costly errors where money is returned for active tax documents.

Hands-off issuer onboarding and monitoring

The `create_company` tool lets your Mastra AI agent onboard new commercial entities into your billing system without human intervention. Your workflow can collect company data, register the issuer, and verify their status in a single run. Running `list_companies` inside a daily cron workflow lets your agent audit your registered issuers and flag inactive profiles. You get a self-healing tax system that monitors its own configuration.

Setup guide

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

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

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

You map the `issue_service_invoice` tool to a Mastra AI workflow step equipped with automatic retries. If the Brazilian government servers return a 500 error, Mastra backs off and retries the call automatically.

Yes, by chaining `cancel_merchandise_invoice` to your e-commerce return triggers inside a Mastra agent. The agent verifies the invoice details using `get_merchandise_invoice` before executing the cancellation.

You register the `create_company` tool within your Mastra AI agent's toolset. When your onboarding agent receives corporate details, it invokes the tool to register the issuer and immediately checks the result.

Yes, using the MCP Server lets your agent audit your configured endpoints with `list_webhooks`. You can build a workflow that alerts your team if a critical webhook URL disappears from your account.

Every transaction is isolated inside an ephemeral V8 sandbox managed by Vinkius. Your sensitive tax payloads and company registration data never touch persistent storage, ensuring absolute compliance with data privacy standards.

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