-1
oportunidados
5 min de leitura ·

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

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

FerramentaOperação da APICréditos
consultar_cnpjGET /v1/cnpjs/{cnpj}1 em basic, 6 em full
buscar_empresasGET /v1/cnpjs1 por empresa retornada, até 20 por página
gerar_filtroPOST /v1/filters/generate1 por chamada
ver_usoGET /v1/usage0

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çãoCusto
Consulta basic1
Consulta full6
Busca1 por empresa retornada (página vazia: 0)
gerar_filtro1 por chamada
ver_uso, status0
Erros, 404 e limites0

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:

PlanoPreçoCréditos/mês
FreeR$ 060
StarterR$ 4915 mil
Pro (Recomendado)R$ 199100 mil
BusinessR$ 699500 mil
ScaleR$ 1.9993 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.

Publicado originalmente em https://cnpj.ia.br/api-cnpj-para-agentes?utm_source=tabnews&utm_medium=article.

Carregando publicação patrocinada...
0