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

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.