Data

Auxiliar.ai CNPJ fetch (BrasilAPI → CNPJ.ws cascade)

Drop-in CNPJ lookup. Returns razão social, primary + secondary CNAEs, regime tributário (Simples Nacional + MEI flags), situação cadastral, full address, QSA. Cascades BrasilAPI → CNPJ.ws on error. One auth surface for the rest of the auxiliar.ai gateway's 220+ Brazilian public-data tools.

Verified: 2026-04-29 (vendor-self-reported)

When to use Auxiliar.ai CNPJ fetch (BrasilAPI → CNPJ.ws cascade)

Choose if

Your agent extracts CNPJs from invoices and needs to enrich them with CNAE (primary + secondary), regime tributário (Simples Nacional + MEI flags), razão social, full address, and QSA before writing to a ledger or coaching the user. Pick this over hand-rolling against BrasilAPI directly when you want (a) automatic fallback to CNPJ.ws on upstream errors, (b) one auth surface for the rest of your Brazilian-public-data agent flow (NFS-e parsing, judicial process, contracts, sanctions), (c) sub-second cached repeat lookups, (d) a clean upgrade path to per- user telemetry + higher rate limits when you mint a token.

Avoid if

You only need a single CNPJ lookup and don't plan to use any other Brazilian-public-data tool — in that case curl BrasilAPI directly (`curl https://brasilapi.com.br/api/cnpj/v1/<cnpj>`) is one less dependency. Or, you need real-time situação cadastral (recently-flipped KYC status) — open-data lag means this cascade is ~30 days behind; use a paid commercial enrichment provider instead.

Risk Flags

  • MEDIUM regulatory Receita Federal open data has ~30-day publication lag. For real-time situação cadastral (a CNPJ that flipped to INAPTA / BAIXADA last week), use a paid commercial enrichment provider — out of scope for this free-tier cascade.
  • LOW vendor_lockin The cascade order (BrasilAPI → CNPJ.ws) is a curated default. If you need a specific provider (e.g., CNPJ.ws for Inscrições Estaduais), call the provider's tool directly via invoke_capability(tool="<provider>_cnpj_fetch") — the cascade is a convenience wrapper, not a gate.

Cost

Type: Free · Free tier: No-auth path goes through anonymous tier (LOW-sensitivity public data, 600 RPM shared across all unauth callers). Mint a personal token via Auxiliar-ai/scripts/issue_internal_token.py to upgrade to external tier (60 RPM per user) or internal tier (6000 RPM, for Dunas-class products) — gives you per-user telemetry and exclusive HIGH_PII tools (Direct Data CPF dossiê etc.). All CNPJ-enrichment fields are free at every tier; the upstream BrasilAPI / CNPJ.ws are themselves free.

Hidden costs

  • Rate-limit hits return 429 — code your enrichment loop to back off and retry.
  • BrasilAPI / CNPJ.ws are sourced from Receita Federal open-data dumps with ~30-day lag; for real-time situação cadastral (KYC at supplier-onboarding time) the lag may matter.

Install

Default

claude mcp add auxiliar npx auxiliar-mcp
# Once installed (no token needed for CNPJ — it's LOW-sensitivity),
# invoke from your agent loop:
invoke_capability(
  tool="fetch_cnpj",
  args={"cnpj": "11.222.333/0001-81"}
)
# Returns:
# {
#   "tool": "fetch_cnpj",
#   "source_module": "backend.sources.br.empresa.cnpj",
#   "elapsed_ms": 678,
#   "result": {
#     "cnpj": "11222333000181",
#     "razao_social": "BANCO DO BRASIL SA",
#     "cnae_fiscal": 6422100,
#     "cnae_fiscal_descricao": "Bancos múltiplos, com carteira comercial",
#     "cnaes_secundarios": [...],
#     "opcao_pelo_simples": false,
#     "opcao_pelo_mei": false,
#     "descricao_situacao_cadastral": "ATIVA",
#     "logradouro": "...", "municipio": "...", "uf": "...",
#     "qsa": [...],
#     "source": "brasilapi"   # or "cnpjws" if cascaded
#   },
#   "scope": {"tier": "anonymous", ...}
# }

Setup docs →

Estimated time to first success: ~2 min

Claude desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "auxiliar": {
      "command": "npx",
      "args": ["-y", "auxiliar-mcp"]
    }
  }
}

Cursor

Add via Cursor's MCP settings UI or .cursor/mcp.json
{ "mcpServers": { "auxiliar": { "command": "npx", "args": ["-y", "auxiliar-mcp"] } } }

Openclaw

Direct HTTP — no MCP install required
# Renatoag-class agents that already speak HTTP can call the gateway directly:
curl -X POST https://api.auxiliar.ai/api/invoke/fetch_cnpj \
  -H "content-type: application/json" \
  -d '{"cnpj": "11.222.333/0001-81"}'
# No auth required for CNPJ (anonymous tier, LOW-sensitivity).

Dependencies

Minimum runtime: Node 18+ (auxiliar-mcp's runtime); the gateway itself is hosted.

Requires: auxiliar-mcp

Composes with: auxiliar-nfs-e, nfs-e-parser, BrasilAPI: CNPJ lookup, CNPJ.ws: free + commercial CNPJ lookup

Distribution

Repository
https://github.com/Tlalvarez/Auxiliar-ai
License
MIT (gateway code); upstream data per Receita Federal open data terms