Documentação API
MCP Server

MCP APICNPJ para consultar CNPJ, buscar empresas e gerar leads com IA.

Servidor MCP HTTP/JSON-RPC para Codex, Claude, ChatGPT, Gemini, Perplexity e agentes internos consultarem CNPJ, pesquisarem empresas por nome, telefone, e-mail, CNAE, cidade e UF, encontrarem sócios, mapearem concorrentes e gerarem listas B2B com segurança.

Abrir playgroundVer logs MCPVer limites
01tools/listdescobre schemas
02planejarCNAE e filtros
03preveramostra curta
04exportarcom aceite LGPD
JSON-RPCHTTP POST

Compatível com clientes MCP remotos e chamadas server-to-server.

15+ toolsLeads, mercado e CNPJ

Consulta CNPJ, busca avançada, sócios, similares, correlacionadas, mercado, prévia e exportação.

LogsIP e user agent

Audite chamadas no dashboard e veja ferramenta, tempo, token, status e consumo.

LGPDTrava de lote

Lote pago exige confirmação explícita e uso responsável.

Resources e prompts

O agente descobre CNAEs, UFs, municípios, schemas, exemplos e prompts antes de chamar tools

Além de tools/list e tools/call, o MCP APICNPJ expõe resources/list, resources/read, prompts/list e prompts/get. Assim Claude, Codex, ChatGPT ou outro agente consegue entender catálogos, enums, documentação e receitas sem montar filtros no escuro.

Resources vivos

apicnpj://cnaes

CNAEs e grupos de atividade econômica para descoberta de nichos e filtros comerciais.

apicnpj://ufs

Estados brasileiros, siglas e nomes normalizados para busca por região.

apicnpj://municipios

Municípios usados em filtros de cidade, UF, CEP e concentração regional.

apicnpj://naturezas-juridicas

Naturezas jurídicas para segmentar empresas, associações, órgãos públicos e sociedades.

apicnpj://qualificacoes-socios

Qualificações do quadro societário para interpretar sócios, administradores e representantes.

apicnpj://paises

Países e códigos usados em cadastros e vínculos societários quando disponíveis.

apicnpj://docs

Documentação resumida para agentes entenderem autenticação, limites, schemas e exemplos.

apicnpj://exemplos

Exemplos de chamadas MCP, REST, filtros de empresas, leads e validação cadastral.

Prompts prontos

gerar_leads_b2b

Gera uma sequência segura para planejar, contar, amostrar e exportar oportunidades comerciais.

pesquisar_concorrentes

Parte de um CNPJ, CNAE ou cidade para encontrar empresas similares e concorrentes.

encontrar_fornecedores

Pesquisa empresas potenciais por segmento, região, porte e disponibilidade de contato.

auto_preencher_crm

Consulta CNPJ e devolve campos prontos para CRM, ERP ou formulário B2B.

validar_fornecedor

Valida situação cadastral, CNAE, endereço, sócios e sinais úteis para onboarding.

analisar_mercado

Compara regiões, CNAEs, volumes estimados e contatos disponíveis para inteligência comercial.

pesquisar_socios

Busca vínculos societários e empresas relacionadas a pessoas do QSA.

Templates

Modelos prontos para nichos comerciais comuns

Restaurantes
{
  "segmento": "restaurantes",
  "cnae_grupo": "56",
  "exigir_email": true,
  "exigir_telefone": true
}
Médicos e clínicas
{
  "segmento": "clinicas medicas",
  "cnae_grupo": "86",
  "exigir_telefone": true
}
Supermercados
{
  "segmento": "supermercados",
  "cnae_grupo": "47",
  "exigir_email": true
}
Transportadoras
{
  "segmento": "transporte rodoviario de carga",
  "cnae_grupo": "49",
  "exigir_telefone": true
}
Indústria metalúrgica
{
  "segmento": "industria metalurgica",
  "cnae_grupo": "24",
  "uf": "SP"
}
Advocacia
{
  "segmento": "advocacia",
  "cnae_grupo": "69",
  "com_email": true
}
Construtoras
{
  "segmento": "construtoras",
  "cnae_grupo": "41",
  "uf": "SP"
}
Empresas sem e-mail
{
  "filtro": "sem_email",
  "objetivo": "identificar lacunas de enriquecimento"
}
Catálogo MCP

Tools organizadas por categoria, metadata, custo e permissões

Consulta

consultar_cnpj, validar cadastro, buscar detalhes de empresa.

Buscar empresas

buscar_empresas, buscar por CNAE, cidade, UF, telefone e e-mail.

Leads

planejar, contar, prever, exportar cortesia e criar lote com aceite LGPD.

Mercado

mapear mercado, ranking por cidade, comparar estados e estimar tamanho do segmento.

Relacionamentos

sócios, empresas relacionadas, correlacionadas por contato e empresas similares.

Exportação

CSV, XLSX, PDF, lotes assíncronos e status por webhook.

Cadastro

auto preencher CRM, ERP, onboarding de fornecedor e validação cadastral.

Utilidades

resources, prompts, schemas, limites, health check e documentação.

ToolEntradaSaídaPermissãoTempoCusto
consultar_cnpjCNPJEmpresa completa em JSONAutenticado~200ms1 consulta
buscar_empresasnome, UF, cidade, CNAELista paginadaAutenticado~300ms1 busca
prospectar_empresas_com_iaobjetivo comercialPlano, amostra e próximos passosAutenticado~600ms1 análise
criar_lote_leadsfiltros + confirmar_lgpdLote assíncronoPlano pagoassíncronofranquia/exportação
Schemas e versões

JSON Schema, enums e versionamento para humanos e agentes de IA

Empresa

cnpj, razao_social, nome_fantasia, situacao_cadastral, abertura, porte, capital_social

Endereco

logradouro, numero, complemento, bairro, cep, municipio, uf

Contato

telefones, emails, origem, validacao, disponibilidade

CNAE

codigo, descricao, principal, secundario, grupo

Socio

nome, qualificacao, data_entrada, faixa_etaria, pais_origem

Lead

empresa, score, motivo, contatos, filtros_aplicados, uso_responsavel

v1Estável

Consulta CNPJ, busca de empresas, sócios, similares, resources e prompts públicos.

v2Em evolução

Busca avançada, lotes, monitoramento, webhooks e recursos fiscais adicionais.

experimentalPreview

Ferramentas de inteligência comercial, ranking por região e análise de mercado.

deprecatedAviso prévio

Tools antigas continuam com compatibilidade até migração documentada.

O que o MCP consulta

Ferramentas para CNPJ, empresas, CNAE, sócios, concorrentes, contatos e leads

O APICNPJ MCP transforma perguntas em linguagem natural em chamadas estruturadas para consultar empresas brasileiras. A IA pode pesquisar CNPJ, razão social, nome fantasia, telefone, e-mail, cidade, estado, CEP, CNAE, situação cadastral, natureza jurídica, capital social, sócios, empresas relacionadas e empresas similares.

Consultar CNPJ

Busca dados cadastrais completos de uma empresa brasileira a partir do CNPJ.

Buscar empresas por nome

Pesquisa razão social, nome fantasia e termos comerciais.

Encontrar empresas por CNAE

Filtra empresas por atividade econômica, UF, cidade, situação cadastral e contato disponível.

Localizar sócios

Pesquisa vínculos societários e empresas relacionadas a um nome de sócio.

Mapear concorrentes

Compara empresas similares por CNAE, cidade, UF e escopo nacional.

Criar listas segmentadas

Planeja filtros, conta mercado, mostra amostra e cria lote com confirmação LGPD.

Enriquecer CRM

Retorna endereço, telefone, e-mail, CNAE, natureza jurídica, capital social e sócios quando disponíveis.

Auditar uso

Registra token, ferramenta, IP, user agent, status e tempo para acompanhar consumo.

Documentação da API CNPJDicionário de campos JSONBuscar empresasGuias técnicos
Limites e headers

API e MCP compartilham consumo do token e expõem headers de rate limit

Sem token3 req/min por IP

Use para descoberta pública, documentação e testes leves.

Token Starter3 req/min

Compartilha limite entre API e MCP no mesmo token.

Planos pagos20 a 500 req/min

Basic 20, Pro 100, Business 250 e Enterprise 500 req/min.

Rolling window60 segundos

Janela deslizante para consumo mais previsível.

HeadersX-RateLimit-*

Leia limite, restante e reset em cada resposta.

X-RateLimit-LimitLimite aplicado ao IP ou token.
X-RateLimit-RemainingQuantidade restante na janela atual.
X-RateLimit-ResetTimestamp Unix em segundos para reset da janela.
Retry-AfterSegundos para aguardar quando houver bloqueio 429.
Dor do mercado

O que o MCP resolve na rotina de vendas, fiscal e dados

Dados de empresa espalhados

Times de vendas, fiscal e produto perdem tempo alternando entre Receita, planilhas, CRM e buscas manuais.

O MCP permite pedir em linguagem natural e receber CNPJ, CNAE, endereço, sócios, contatos e empresas relacionadas em um fluxo único.

Leads sem contexto

Listas compradas costumam vir sem CNAE claro, recorte regional, validação de contato ou explicação do motivo da oportunidade.

A IA primeiro planeja filtros, conta o mercado, mostra amostra e só exporta depois da confirmação do usuário.

Pesquisa de concorrentes lenta

Encontrar empresas similares por CNAE, cidade, UF e vínculos por contato ou sócio é trabalhoso sem ferramentas conectadas.

Tools de similares, correlacionadas e sócios ajudam o agente a montar mapas de concorrência e expansão regional.

Risco operacional e LGPD

Automação sem trilha de auditoria pode gerar lote indevido, abuso de contato ou uso de token compartilhado.

O MCP registra logs, separa tokens por cliente e exige confirmar_lgpd e uso_responsavel para lote pago.
Simulador

Como uma IA usa o APICNPJ MCP no dia a dia

Codex

Validar empresa antes de preencher cadastro

Você

Tenho o CNPJ 05.729.230/0001-00. Valida e monta os campos para meu formulário?

Codex

Vou chamar consultar_cnpj e retornar razão social, situação, CNAE, endereço, contatos e sócios sem inventar campos ausentes.

Tool

consultar_cnpj({ cnpj: "05729230000100" })

Codex

Empresa localizada. Sugestão de preenchimento: razão social, nome fantasia quando houver, endereço completo, CNAE principal, situação cadastral e quadro societário. Campos sem dado devem ficar vazios ou como não informado.

Claude

Gerar oportunidades por região e CNAE

Você

Quero restaurantes ativos em SP com e-mail e telefone para validar campanha.

Claude

Vou planejar o público, sugerir CNAEs, contar o mercado e mostrar uma amostra curta antes de exportar.

Tool

prospectar_empresas_com_ia({ segmento: "restaurantes", uf: "SP", exigir_email: true, exigir_telefone: true, limit: 8 })

Claude

Encontrei filtros recomendados por CNAE e UF. Próximo passo seguro: revisar amostra e, se fizer sentido, exportar cortesia ou criar lote com aceite LGPD.

Agente SDR

Achar sócios e empresas correlacionadas

Você

Pesquise empresas ligadas ao sócio João da Silva e veja contatos relacionados.

Agente

Vou buscar sócios relacionados, enriquecer CNPJs relevantes e procurar correlação por e-mail, telefone ou endereço quando houver.

Tool

buscar_socios_relacionados({ nome: "JOAO DA SILVA", limit: 10 })

Agente

Resultado organizado por CNPJ, razão social, cidade, UF, CNAE e vínculo. Use consultar_cnpj nos registros mais relevantes antes do contato comercial.

Receitas de bolo

Fluxos prontos para qualquer IA entender e executar

Receita selecionada

Gerar oportunidades por segmento

Transforme uma frase comercial em CNAE, conte o mercado, veja amostra e só depois exporte uma lista segmentada.

  1. Descobrir ferramentas com tools/list.
  2. Chamar prospectar_empresas_com_ia com objetivo, região e exigência de contato.
  3. Validar CNAE, total estimado e amostra.
  4. Exportar cortesia ou criar lote somente com aceite LGPD.
Integração

Como plugar em Codex, Claude ou agente próprio

Nome técnico do servidor MCP: apicnpj-mcp. Endpoint oficial: POST /api/mcp.

Codex

Use a URL HTTP do MCP e passe Authorization por header no conector.

Claude

Adicione o servidor remoto APICNPJ e deixe a IA chamar tools/list antes de qualquer ação.

Agentes internos

Use JSON-RPC direto em /api/mcp para automações, SDRs digitais e enriquecimento de CRM.

{
  "mcpServers": {
    "apicnpj": {
      "url": "https://apicnpj.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${APICNPJ_API_KEY}"
      }
    }
  }
}
Playground MCP

Teste como um cliente MCP real

Sem token, use initialize, tools/list, resources/read e prompts/get. Tools que consultam dados exigem Authorization.

Tempo: 0msHeaders: X-RateLimit-*Payload: JSON-RPCRaw JSON
RequestPOST /api/mcp
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "planejar_leads_quentes",
    "arguments": {
      "objetivo": "restaurantes em SP com e-mail e telefone",
      "segmento": "restaurantes",
      "uf": "SP",
      "exigir_email": true,
      "exigir_telefone": true,
      "quantidade_desejada": 1000
    }
  }
}
Responseaguardando
{
  "dica": "Clique em executar para testar o MCP em tempo real."
}
Instalação

Clientes, IDEs e frameworks onde o MCP APICNPJ pode ser conectado

Claude Desktop

Configure mcpServers com URL HTTPS e header Authorization.

Cursor e VSCode

Use servidor remoto HTTP ou bridge local apontando para /api/mcp.

Windsurf, Cline e Roo Code

Cadastre o MCP como servidor remoto e teste tools/list.

Codex CLI

Adicione o servidor APICNPJ e use prompts para consultar empresas por linguagem natural.

OpenAI Agents SDK

Use MCP como ferramenta externa para agentes de prospecção e validação cadastral.

LangChain, LlamaIndex, CrewAI e AutoGen

Conecte via JSON-RPC HTTP ou adapter MCP compatível.

Observabilidade

Logs MCP para auditoria, replay, bloqueio de sessão e análise de uso

Tempo médio

Latência por tool, status HTTP e janela de execução.

Tokens e sessão

Token usado, agente conectado, bloqueio/desbloqueio e revogação.

Ferramenta chamada

Nome da tool, argumentos principais e resposta resumida.

Usuário e origem

IP, user agent, origem, app cliente e workspace quando informado.

Erros

Código, mensagem segura, stack interno oculto e replay do payload quando permitido.

Replay

Reexecutar teste no playground com o mesmo request, headers e modo MCP.

Abrir dashboard MCP
Changelog

Histórico de mudanças para agentes não dependerem de documentação desatualizada

Adicionadas resources/list, prompts/list e catálogo de schemas para agentes.

Nova tool encontrar_empresas_similares para concorrentes por CNAE, cidade e UF.

Logs MCP no dashboard com token, IP, user agent, status, erro e latência.

Fluxo de monitoramento e webhooks para tarefas assíncronas.

Roadmap comercial

Tools que posicionam o MCP como máquina de prospecção B2B

descobrir_nichos_promissores()listar_empresas_recem_abertas()mapear_concorrentes()gerar_argumentos_comerciais()analisar_mercado()encontrar_fornecedores()encontrar_clientes_parecidos()enriquecer_lead()validar_cadastro()estimar_tamanho_do_mercado()gerar_lista_para_SDR()identificar_empresas_sem_site()identificar_empresas_sem_email()empresas_com_whatsapp()ranking_por_cidade()ranking_por_cnae()comparar_cidades()comparar_estados()
Bootstrap

Cadastro por IA com e-mail, OTP e token MCP

A chave MCP/API só é liberada depois da validação do código enviado por e-mail. Isso evita criação automática abusiva de tokens e mantém uma trilha mínima de consentimento. Sem token, o MCP aceita 3 requisições por minuto por IP; com token, o limite segue o plano e é compartilhado com o consumo da API.

POST /api/mcp/auth/start
{
  "nome": "Bruno Duarte",
  "email": "[email protected]",
  "telefone": "11999999999"
}

POST /api/mcp/auth/verify
{
  "email": "[email protected]",
  "codigo": "123456"
}

Resposta esperada:
{
  "api_key": "sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "mcp_url": "https://apicnpj.com/api/mcp"
}
Ferramentas

Mapa rápido das tools disponíveis

planejar_leads_quentes

{"objetivo":"restaurantes em SP com e-mail e telefone","segmento":"restaurantes","uf":"SP","exigir_email":true,"exigir_telefone":true,"quantidade_desejada":1000}

contar_leads_quentes

{"cnae":"5611201","uf":"SP","com_email":true,"com_telefone":true,"situacao":"ativa"}

prever_leads_quentes

{"cnae":"5611201","uf":"SP","com_email":true,"com_telefone":true,"situacao":"ativa","limit":5}

exportar_leads_gratis

{"cnae":"5611201","uf":"SP","com_email":true,"com_telefone":true,"quantidade":5,"fingerprint":"mcp-playground"}

criar_lote_leads

{"cnae":"5611201","uf":"SP","com_email":true,"com_telefone":true,"quantidade":1000,"formato":"csv","confirmar_lgpd":true,"uso_responsavel":true}

consultar_cnpj

{"cnpj":"05729230000100"}

buscar_empresas

{"nome":"mercado","uf":"SP","limit":10}

buscar_socios_relacionados

{"nome":"JOAO DA SILVA","limit":10}

descobrir_segmentos_cnae

{"termo":"restaurantes","uf":"SP","limit":20}

mapear_mercado_empresas

{"segmento":"restaurantes","uf":"SP","com_email":true,"com_telefone":true,"limit":8}

buscar_empresas_por_regiao_cnae

{"cnae":"5611201","uf":"SP","cidade":"SAO PAULO","com_email":true,"limit":10}

encontrar_empresas_relacionadas

{"kind":"email","value":"[email protected]","limit":10}

encontrar_empresas_similares

{"cnpj":"05729230000100","escopo":"uf","limit":10}

prospectar_empresas_com_ia

{"objetivo":"restaurantes em SP com e-mail e telefone","segmento":"restaurantes","uf":"SP","exigir_email":true,"exigir_telefone":true,"limit":8}

gerar_leads_quentes

{"cnae":"5611201","uf":"SP","com_email":true,"com_telefone":true,"limit":5}