🇧🇷 Brazil MCP Suite — The Ultimate Brazilian Business Toolkit for AI Agents

Brazil MCP Suite is a production-ready, highly resilient Model Context Protocol (MCP) server bundle designed to give autonomous AI agents full operational capabilities inside the Brazilian corporate, fiscal, postal, and financial ecosystems.

Whether your AI agent needs to onboard vendors, validate corporate entities, generate real-time Pix payment QR Codes, issue municipal tax invoices (NFSe), or dispatch automated notifications via WhatsApp, Brazil MCP provides a unified, standardized interface with zero friction.

---

🌟 Why Brazil MCP?

Navigating Brazilian regulatory APIs often involves fragmented documentation, inconsistent uptime, and complex authentication. Brazil MCP Suite solves this by introducing intelligent abstraction layers:

• 🔄 Multi-Provider Automatic Failover: If a primary public endpoint experiences downtime (e.g., BrasilAPI), the internal engine automatically switches to secondary providers (ReceitaWS, ViaCEP) via built-in Circuit Breakers.
• ⚡ Smart Caching & Rate Limiting: Out-of-the-box support for distributed serverless caching via Upstash Redis REST API or traditional Redis TCP, backed by a seamless in-memory fallback.
• 🛡️ Type-Safe & Compliant: Strict schema validation with Zod guarantees valid input formatting (CPF, CNPJ, CEP, phone numbers) before emitting external requests.

---

📦 Core Capabilities (16 Specialized Tools)

🏢 CNPJ — Corporate Intelligence (5 Tools)

Query official data from the Brazilian Federal Revenue Service (Receita Federal):

• cnpj_lookup: Fetch comprehensive legal profile (trade name, share capital, tax status, opening date).
• cnpj_validate: Verify mathematical checksum digits of any CNPJ string.
• cnpj_partners: Extract full corporate governance structure and partner shareholdings (QSA).
• cnpj_activities: Retrieve primary and secondary economic classification codes (CNAE).
• cnpj_address: Query verified headquarters address and location metadata.

📍 CEP — Address & Postal Lookup (2 Tools)

Instant ZIP code resolution powered by automated multi-gateway fallbacks:

• cep_lookup: Resolve street name, neighborhood, city, and state (UF) by 8-digit CEP.
• cep_validate: Fast format and regex structure check.

💰 Pix — Instant Payments Gateway (4 Tools)

Directly interact with major Brazilian payment acquiring networks (Asaas, AbacatePay, Efi/Gerencianet, MercadoPago, Pagar.me, PagSeguro, Stripe):

• pix_create_charge: Generate instant Pix QR Codes and Copy & Paste (pix_copia_e_cola) billing strings.
• pix_check_status: Track real-time settlement status (pending, paid, cancelled).
• pix_list_charges: Query historical transaction statements across custom date ranges.
• pix_cancel_charge: Void open/unexpired billing requests.

🧾 NFSe — Municipal Tax Invoice Issuance (3 Tools)

Automate electronic service tax invoicing compliant with national standards (via Focus NFe engine):

• nfse_emit: Issue legally compliant electronic service invoices (NFSe) with automated tax withholding calculations.
• nfse_status: Monitor municipal authorization status and retrieve downloadable XML/PDF links.
• nfse_cancel: Request formal invoice cancellation with regulatory audit justifications.

💬 WhatsApp — Cloud Messaging Automation (2 Tools)

Communicate with clients via the official Meta Cloud API:

• whatsapp_send_text: Send direct text notifications and conversational updates to Brazilian phone numbers.
• whatsapp_send_template: Dispatch official pre-approved interactive template messages with dynamic parameters.

---

🚀 Use Cases for AI Assistants

1. Automated KYC & Vendor Onboarding: Let your agent receive a CNPJ, validate its tax situation, extract legal partners, and confirm its physical address in seconds.
2. Autonomous Billing Agents: When a user requests a purchase, the agent issues a Pix charge, displays the QR Code in chat, polls for confirmation, and automatically triggers delivery upon settlement.
3. End-to-End Accounting Automation: Automatically generate and emit municipal NFSe tax invoices immediately after a Pix payment is detected, sending the PDF link directly to the customer's WhatsApp.

---

⚙️ Configuration & Environment Variables

Public lookups (CNPJ and CEP) work out-of-the-box for free without any configuration. For transactional actions (Pix, NFe, WhatsApp) or distributed caching, configure the following optional environment variables:

Variable	Description
PIX_PROVIDER	Preferred Pix gateway (asaas, abacatepay, efi, mercadopago, pagarme, pagseguro, stripe)
PIX_API_KEY	API key / Access token for the selected Pix acquiring gateway
NFE_API_TOKEN	API Token for electronic invoice emission (Focus NFe)
WHATSAPP_TOKEN	Access Token for Meta Cloud API (WhatsApp Business)
WHATSAPP_PHONE_ID	Official Phone Number ID registered on Meta Cloud API
UPSTASH_REDIS_REST_URL	(Optional) Upstash REST endpoint for serverless zero-TCP caching
UPSTASH_REDIS_REST_TOKEN	(Optional) Upstash REST authentication token