DEV Community: Fred Estante

Como dar a um agente acesso à base de empresas do Brasil em um comando (MCP)

Fred Estante — Mon, 21 Sep 2026 14:06:43 +0000

O agente precisa responder perguntas como "essa empresa existe, está ativa, faz o quê, fica onde e como entro em contato". A resposta existe na base da Receita Federal. O problema é o caminho até ela.

As opções manuais cobram pedágio. Planilha baixada perde a data de referência na segunda semana. Scraper de portal quebra no primeiro redesign. CSV mensal pesa gigabytes e exige pipeline próprio. E dado cadastral sem data não sustenta decisão: situação, endereço e quadro societário mudam, e quem consome precisa saber de quando é a foto.

Pense no onboarding: o agente recebe um CNPJ e precisa dizer se a empresa está ativa, se é optante do Simples, qual o CNAE principal e em que município fica. Ou na prospecção: listar empresas de um setor e cidade, com telefone disponível, e contar quantas são antes de percorrer a lista. Nos dois casos, o agente precisa de fonte única, datada e com erro tipado — não de texto plausível.

O cnpj.ia.br expõe a base como servidor MCP remoto. O agente chama ferramentas, cada resposta informa a data da base em meta.data_as_of, e o custo em créditos é conhecido antes da chamada. A base é a da Receita Federal, atualizada mensalmente. Abaixo: o servidor em duas frases, a configuração por cliente, as quatro ferramentas, o custo e os limites.

Um servidor MCP remoto, em duas frases

Um servidor MCP remoto expõe ferramentas por HTTP para qualquer cliente compatível: o agente descobre as ferramentas por tools/list e chama com a chave da sua conta. No cnpj.ia.br, são quatro ferramentas sobre a base de empresas do Brasil, com a mesma chave e o mesmo custo em créditos da API REST.

Configuração

Transporte HTTP na URL https://mcp.cnpj.ia.br, autenticação pela chave da conta no header Authorization: Bearer. A chave fica guardada no cliente do agente e viaja só no header de cada chamada, para validação. Com a conexão feita, tools/list devolve as quatro ferramentas e nada mais.

Claude Code resolve em um comando:

claude mcp add --transport http cnpjia https://mcp.cnpj.ia.br \
  --header "Authorization: Bearer $CNPJIA_KEY"

Claude Desktop só aceita servidor local no claude_desktop_config.json, por isso usa a ponte mcp-remote:

{
  "mcpServers": {
    "cnpjia": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.cnpj.ia.br",
               "--header", "Authorization: Bearer ${CNPJIA_KEY}"],
      "env": { "CNPJIA_KEY": "cnpj_live_…" }
    }
  }
}

Cursor, em .cursor/mcp.json:

{
  "mcpServers": {
    "cnpjia": {
      "url": "https://mcp.cnpj.ia.br",
      "headers": { "Authorization": "Bearer [REDACTED]" }
    }
  }
}

Windsurf usa o mesmo JSON com serverUrl no lugar de url. Codex CLI lê a chave da variável de ambiente a cada início, sem gravar no config:

export CNPJIA_KEY="cnpj_live_…"
codex mcp add cnpjia --url https://mcp.cnpj.ia.br --bearer-token-env-var CNPJIA_KEY

Os caminhos de arquivo variam por cliente; a chave, nunca: fica sempre do lado do agente, em arquivo local ou variável de ambiente.

As quatro ferramentas

Ferramenta	Operação da API	Créditos
`consultar_cnpj`	`GET /v1/cnpjs/{cnpj}`	1 em `basic`, 6 em `full`
`buscar_empresas`	`GET /v1/cnpjs`	1 por empresa retornada, até 20 por página
`gerar_filtro`	`POST /v1/filters/generate`	1 por chamada
`ver_uso`	`GET /v1/usage`	0

Uma pergunta em linguagem natural para cada uma:

consultar_cnpj em basic: "Qual é a situação cadastral e o CNAE principal do CNPJ 00.000.000/0001-91?"
consultar_cnpj em full: "Me dá o telefone e os sócios do Banco do Brasil, CNPJ 00.000.000/0001-91."
gerar_filtro e depois buscar_empresas: "Quantas empresas de software ativas existem em Florianópolis?" A primeira página já traz a contagem com teto.
ver_uso: "Quantos créditos ainda tenho este mês?"

gerar_filtro recebe uma descrição ("padarias ativas em Curitiba optantes do Simples") e devolve os filtros estruturados que buscar_empresas aceita. É a ponte entre a pergunta do usuário e a busca. Custa 1 crédito por chamada, com resultado ou sem.

O agente decide o perfil (basic ou full) a partir do pedido. Para economizar, oriente no prompt do sistema a usar basic e só pedir full quando has_phone ou has_email vierem verdadeiros. Esses sinais do basic dizem se o full teria contato para mostrar.

A busca pagina por cursor: repete com meta.next_cursor até vir null. A primeira página já traz meta.total_count_capped, a contagem com teto — o agente responde "quantas são" antes de percorrer tudo, e cada empresa retornada custa 1 crédito.

Custo em créditos e o plano gratuito

O peso de cada operação, em créditos:

Operação	Custo
Consulta `basic`	1
Consulta `full`	6
Busca	1 por empresa retornada (página vazia: 0)
`gerar_filtro`	1 por chamada
`ver_uso`, `status`	0
Erros, 404 e limites	0

O plano gratuito inclui 60 créditos grátis por mês: 60 consultas basic ou 10 full. A chave nasce com 15 créditos; o e-mail verificado libera os 60 do mês. Os planos pagos sobem em créditos e requisições por minuto:

Plano	Preço	Créditos/mês
Free	R$ 0	60
Starter	R$ 49	15 mil
Pro (Recomendado)	R$ 199	100 mil
Business	R$ 699	500 mil
Scale	R$ 1.999	3 milhões

Quando a franquia acaba, a API responde 402 quota_exceeded: hard cap, nada é cobrado sem uma ação sua. Erros nunca consomem crédito, e 404 not_found é resultado (CNPJ válido que não existe na base), não falha.

Limites e o que o servidor NÃO faz

Não devolve CPF completo. Sócio pessoa física sai com CPF mascarado (***123456**) ou nulo. Nunca completo.
Não devolve dado sem data. Consulta, busca e filtro informam meta.data_as_of em toda resposta. Nenhum campo reflete o instante da chamada.
No plano gratuito, buscar_empresas responde insufficient_plan. A ferramenta aparece em tools/list, mas não executa sem plano pago. As outras três funcionam no Free.
O limite de requisições por minuto é o do plano da conta, somando agente e API REST. Um agente em loop atinge rate_limited rápido; a resposta traz Retry-After e o agente deve esperar.
O agente não compra créditos nem muda de plano. Crédito e plano se gerenciam no portal, por uma pessoa. A chave fica no cliente; se um agente sair do controle, revogue a chave no portal. A API recusa na próxima chamada e o MCP em até 60 segundos.

Configuração completa, exemplos de perguntas e referência por ferramenta: Servidor MCP.

CNPJ alfanumérico: o que muda no seu sistema e como validar o dígito

Fred Estante — Mon, 21 Sep 2026 14:06:42 +0000

Desde 2026 a Receita Federal emite CNPJs alfanuméricos. As oito posições da raiz e as quatro da ordem podem conter letras e dígitos. Os dois dígitos verificadores continuam numéricos.

Um CNPJ numérico virou um caso particular do formato novo. Os CNPJs que já existem não mudam de número e continuam válidos. Nenhuma base precisa de migração de dados. O trabalho é outro: aceitar letras onde o sistema só aceitava dígito.

Se o seu cadastro valida com ^\d{14}$, guarda em coluna numérica ou usa máscara fixa de dígito, ele vai rejeitar documento válido. Este artigo mostra o formato, o que quebra, a regra do dígito com um exemplo calculado passo a passo e como a API do cnpj.ia.br trata os dois formatos.

O formato

Parte	Posições	Conteúdo
Raiz	1 a 8	Letras maiúsculas ou dígitos. Identifica a empresa, comum a matriz e filiais.
Ordem	9 a 12	Letras maiúsculas ou dígitos. Identifica o estabelecimento.
Dígitos verificadores	13 e 14	Sempre numéricos. Módulo 11 sobre o valor ASCII menos 48 de cada posição anterior.

Dois exemplos. Numérico: 00.000.000/0001-91, do Banco do Brasil. Alfanumérico: 12.ABC.345/01DE-35, exemplo de formato do contrato da API.

O formato antigo continua válido, os números existentes não mudam, e a rotina nova aceita os dois formatos. Quem atualiza a validação uma vez cobre o estoque e o fluxo novo.

Por que `bigint` quebra e `varchar(14)` sobrevive

Três motivos, em ordem de dano.

1. Letras não cabem em número. 12ABC34501DE35 não é inteiro. A primeira inserção de um CNPJ alfanumérico em coluna BIGINT ou NUMERIC(14) falha. Em alguns modos de banco, pior: trunca em silêncio e grava lixo.

2. Zero à esquerda some. 00000000000191 como inteiro vira 191. Toda leitura precisa reaplicar padding com LPAD, e toda comparação direta com string falha sem aviso.

3. Pontuação varia. 00.000.000/0001-91 e 00000000000191 são a mesma empresa em duas strings distintas. Coluna numérica resolve esse caso por acidente e quebra nos dois anteriores.

A forma que sobrevive: texto de 14 caracteres, maiúsculas, sem pontuação. O fluxo de entrada fica assim:

Converte para maiúsculas.
Remove pontos, barra, hífen e espaços.
Valida comprimento (14) e dígitos verificadores.
Guarda na forma normalizada. Formata só na exibição.

Máscaras de entrada no padrão ##.###.###/####-## passam a aceitar letras nas doze primeiras posições. Os dois últimos campos continuam numéricos. Comparações e chaves estrangeiras usam a forma normalizada que a API devolve.

Procure no código por \d{14}, isdigit, parseInt, BIGINT e máscara fixa de dígito. Cada ocorrência é um ponto que rejeita ou corrompe CNPJ alfanumérico.

A regra do dígito verificador

Módulo 11, em duas passadas. A regra nova coincide com a antiga quando só há dígitos. A diferença: cada caractere entra na soma pelo seu valor ASCII menos 48. Dígitos valem 0 a 9. Letras maiúsculas valem 17 (A) a 42 (Z).

Primeira passada: multiplique os doze primeiros caracteres pelos pesos 5 4 3 2 9 8 7 6 5 4 3 2 e some. Tire o resto da divisão por 11. Resto menor que 2 dá dígito 0. Senão, o dígito é 11 − resto. Esse é o primeiro verificador.

Segunda passada: repita com os treze caracteres (os doze mais o primeiro verificador) e os pesos 6 5 4 3 2 9 8 7 6 5 4 3 2. O resultado é o segundo verificador.

Se o par calculado bate com o par informado, o formato é válido. Dígito certo não prova existência; prova que o número passou na checagem. Sequências repetidas, como 00000000000000, passam no cálculo e são rejeitadas à parte.

Exemplo passo a passo: `12ABC34501DE35`

Normalizado (sem pontuação, maiúsculas): 12ABC34501DE35. Valores de cada caractere (ASCII − 48):

Caractere	1	2	A	B	C	3	4	5	0	1	D	E
Valor	1	2	17	18	19	3	4	5	0	1	20	21

Primeira passada, pesos 5 4 3 2 9 8 7 6 5 4 3 2:

1×5 + 2×4 + 17×3 + 18×2 + 19×9 + 3×8 + 4×7 + 5×6 + 0×5 + 1×4 + 20×3 + 21×2
= 5 + 8 + 51 + 36 + 171 + 24 + 28 + 30 + 0 + 4 + 60 + 42
= 459
459 mod 11 = 8 → primeiro dígito = 11 − 8 = 3

Segunda passada, com o 3 calculado e pesos 6 5 4 3 2 9 8 7 6 5 4 3 2:

1×6 + 2×5 + 17×4 + 18×3 + 19×2 + 3×9 + 4×8 + 5×7 + 0×6 + 1×5 + 20×4 + 21×3 + 3×2
= 6 + 10 + 68 + 54 + 38 + 27 + 32 + 35 + 0 + 5 + 80 + 63 + 6
= 424
424 mod 11 = 6 → segundo dígito = 11 − 6 = 5

Par calculado 35. Par informado 35. Formato válido.

Código

Python, curto, sem dependência:

PESOS_1 = (5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2)
PESOS_2 = (6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2)

def _dv(soma: int) -> int:
    resto = soma % 11
    return 0 if resto < 2 else 11 - resto

def cnpj_valido(cnpj: str) -> bool:
    n = cnpj.upper().replace(".", "").replace("/", "").replace("-", "").strip()
    if len(n) != 14 or len(set(n)) == 1:
        return False
    vals = [ord(c) - 48 for c in n[:12]]
    d1 = _dv(sum(v * p for v, p in zip(vals, PESOS_1)))
    d2 = _dv(sum(v * p for v, p in zip([*vals, d1], PESOS_2)))
    return n[12:] == f"{d1}{d2}"

cnpj_valido("12.ABC.345/01DE-35") devolve True. cnpj_valido("00.000.000/0001-91") devolve True. cnpj_valido("00.000.000/0001-92"), com o último dígito trocado, devolve False.

Roda em microssegundos, sem rede: elimina erro de digitação no formulário e separa linhas inválidas no lote antes de gastar consulta.

Como a API do cnpj.ia.br trata o formato

A API aceita o formato antigo e o novo, com ou sem pontuação, minúsculas ou maiúsculas. Remove pontos, barra e hífen antes de validar, valida os dígitos pelo algoritmo alfanumérico e devolve cnpj e raiz_cnpj normalizados. Nada muda nos endpoints nem nos créditos.

# numérico, com e sem pontuação: a mesma empresa
curl "https://api.cnpj.ia.br/v1/cnpjs/00000000000191" -H "Authorization: Bearer $CNPJIA_KEY"
curl "https://api.cnpj.ia.br/v1/cnpjs/00.000.000/0001-91" -H "Authorization: Bearer $CNPJIA_KEY"

# alfanumérico (exemplo de formato do contrato)
curl "https://api.cnpj.ia.br/v1/cnpjs/12.ABC.345/01DE-35" -H "Authorization: Bearer $CNPJIA_KEY"

Resposta resumida para o Banco do Brasil, perfil full:

{
  "data": {
    "cnpj": "00000000000191",
    "razao_social": "BANCO DO BRASIL SA",
    "situacao_cadastral": { "codigo": "02", "descricao": "Ativa" },
    "socios": [
      { "nome": "NOME DO DIRIGENTE", "cnpj_cpf_socio": "***123456**" }
    ]
  },
  "meta": {
    "profile": "full",
    "source": "rfb_open_data+oportunidados",
    "data_as_of": "2026-08-01",
    "credits_charged": 6
  }
}

Quatro comportamentos para a sua integração:

Formato ou dígito inválido responde 400 invalid_cnpj, sem custo.
CNPJ válido que não existe na base responde 404 not_found, também sem custo.
Toda resposta informa a data da base em meta.data_as_of. A base é a da Receita Federal, atualizada mensalmente.
CPF de sócio sai mascarado ou nulo, nunca completo.

O basic custa 1 crédito; o full, 6. O plano gratuito inclui 60 créditos por mês.

Detalhe do formato e dos campos: CNPJ alfanumérico na API.