API de CNPJ para agentes

Um agente que precisa saber se uma empresa existe, o que ela faz, onde está e como contatá-la resolve isso com quatro ferramentas MCP sobre a base da Receita Federal de agosto/2026: consultar_cnpj, buscar_empresas, gerar_filtro e ver_uso. A chave é a mesma da API REST, o custo em créditos é o mesmo, e consulta, busca e filtro trazem a data da base em meta.data_as_of.

O fluxo em três passos

1. Crie a chave e cole no cliente

   Uma chave da conta, no header Authorization. Claude Code, Cursor e Windsurf conectam direto ao servidor remoto; Claude Desktop pela ponte mcp-remote.

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

2. Deixe o agente perguntar em português

   gerar_filtro transforma a pergunta em filtros da busca; buscar_empresas pagina por cursor; consultar_cnpj traz o cadastro ou o perfil completo.

   "Liste padarias ativas em Curitiba optantes do Simples e me diga quantas são."

3. Controle o gasto pelo próprio agente

   ver_uso devolve franquia, consumo e reset. A chave fica no cliente; o agente não compra créditos nem muda de plano.

   ver_uso → credits_remaining, cycle_reset_at, rpm

Código pronto

O servidor é remoto e fala HTTP. A configuração muda por cliente; a chave fica sempre do lado do agente.

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

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

import os
from openai import OpenAI

client = OpenAI()
resp = client.responses.create(
    model="gpt-5",
    tools=[{
        "type": "mcp",
        "server_label": "cnpjia",
        "server_url": "https://mcp.cnpj.ia.br",
        "headers": {"Authorization": f"Bearer {os.environ['CNPJIA_KEY']}"},
        "require_approval": "never",
    }],
    input="Quantas empresas de software ativas existem em Florianópolis?",
)
print(resp.output_text)

Claude Desktop não aceita servidor remoto com header no arquivo local de configuração; a ponte mcp-remote resolve. Windsurf usa serverUrl no lugar de url. Os quatro casos estão em Servidor MCP.

O que o agente passa a responder

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

O agente decide o perfil a partir do pedido. Se quiser economizar, oriente no prompt do sistema a usar basic e só pedir full quando has_phone ou has_email vierem verdadeiros.

Campos mais usados

Limites que o agente precisa respeitar

• O limite de requisições por minuto é da conta, somando agente e API REST. Um agente em loop chega a rate_limited; a resposta traz Retry-After e o agente deve esperar.
• buscar_empresas está nos planos pagos. No Free a ferramenta aparece em tools/list, mas responde insufficient_plan com um link para os planos, sem consumir crédito.
• Chave revogada é recusada pela API na próxima chamada e pelo MCP em até 60 segundos.