Conecte sua IA à base CNPJLeads

Visão geral

O Model Context Protocol (MCP) é o padrão aberto que permite a assistentes de IA usar ferramentas externas. O servidor MCP da CNPJLeads dá ao seu assistente acesso direto à nossa base de empresas da Receita Federal.

Em vez de montar filtros e exportar planilhas, você pede em português — "liste clínicas odontológicas ativas em São José/SC com telefone" — e a IA escolhe os códigos CNAE, encontra o município, consulta a base e organiza o resultado.

URL do servidor:

https://cnpjleads.com/api/mcp

Transporte:

Streamable HTTP (POST, JSON)

Autenticação:

Authorization: Bearer SEU_TOKEN

Versões do protocolo:

2025-06-18, 2025-03-26, 2024-11-05

Quem pode usar

O MCP é exclusivo para clientes com plano ativo. Sua conta tem acesso quando possui:

• uma assinatura ativa dentro do período vigente (com 3 dias de tolerância após o vencimento); ou
• a compra de um plano/pacote paga nos últimos 30 dias.

Créditos de bônus, indicação ou do plano gratuito não liberam o MCP sozinhos. O acesso é liberado assim que o pagamento é confirmado e suspenso automaticamente quando o plano deixa de estar ativo.

Início rápido

1. 1

   Gere seu token de API

   No seu perfil, clique em "Gerar token de API". É o mesmo token da API REST. Abrir meu perfil

2. 2

   Adicione o servidor ao seu cliente

   Copie a configuração do seu aplicativo abaixo e troque SEU_TOKEN pelo token gerado.

3. 3

   Converse

   Reinicie o aplicativo e peça, por exemplo: "Quantos créditos eu tenho na CNPJLeads?". Se ele responder, está conectado.

Configurar seu cliente

Em todos os exemplos, substitua SEU_TOKEN pelo seu token de API.

Claude Code

claude mcp add --transport http cnpjleads https://cnpjleads.com/api/mcp \
  --header "Authorization: Bearer SEU_TOKEN"

Rode no terminal. Use --scope user para disponibilizar em todos os projetos. Confira com "claude mcp list".

Claude Desktop

Em Configurações → Desenvolvedor → Editar configuração, abra o claude_desktop_config.json e adicione:

{
  "mcpServers": {
    "cnpjleads": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://cnpjleads.com/api/mcp",
        "--header", "Authorization: Bearer SEU_TOKEN"
      ]
    }
  }
}

Requer Node.js 18+ instalado (o mcp-remote faz a ponte para servidores HTTP com cabeçalho de autenticação).

Cursor

Em Settings → MCP → Add new global MCP server (arquivo ~/.cursor/mcp.json) ou em .cursor/mcp.json no projeto:

{
  "mcpServers": {
    "cnpjleads": {
      "url": "https://cnpjleads.com/api/mcp",
      "headers": { "Authorization": "Bearer SEU_TOKEN" }
    }
  }
}

VS Code (GitHub Copilot)

Crie .vscode/mcp.json no projeto. O VS Code pedirá o token na primeira execução e o guardará de forma segura:

{
  "inputs": [
    { "id": "cnpjleads-token", "type": "promptString", "description": "CNPJLeads API token", "password": true }
  ],
  "servers": {
    "cnpjleads": {
      "type": "http",
      "url": "https://cnpjleads.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:cnpjleads-token}" }
    }
  }
}

Windsurf

Em Settings → Cascade → MCP servers → View raw config (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "cnpjleads": {
      "serverUrl": "https://cnpjleads.com/api/mcp",
      "headers": { "Authorization": "Bearer SEU_TOKEN" }
    }
  }
}

Outros clientes

Qualquer cliente compatível com MCP via Streamable HTTP funciona: informe a URL do servidor e o cabeçalho Authorization: Bearer SEU_TOKEN. Se o cliente só suporta stdio, use a ponte "npx mcp-remote" como no exemplo do Claude Desktop.

Testar com curl

Útil para validar o token e o plano antes de configurar o aplicativo (não consome créditos):

curl -s -X POST https://cnpjleads.com/api/mcp \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'

Ferramentas

A IA decide sozinha quais ferramentas chamar. Esta é a referência completa, gerada a partir do próprio servidor.

* obrigatório. Porte: 01=ME, 03=EPP, 05=Demais. Situação cadastral: 01=Nula, 02=Ativa, 03=Suspensa, 04=Inapta, 08=Baixada. CNPJs alfanuméricos (2026) são aceitos.

Prompt pronto

O servidor também oferece o prompt prospect_leads (argumentos: segment e location), que conduz a IA por uma prospecção completa: encontra CNAE e cidade, confere o saldo e só então busca empresas ativas com telefone.

Exemplos de pedidos

Experimente pedir ao seu assistente:

• “Quais códigos CNAE correspondem a academias de ginástica? Quantas empresas há em cada um?”
• “Liste 20 clínicas odontológicas ativas em Campinas/SP com telefone, numa tabela com razão social, telefone e bairro.”
• “Traga a ficha completa do CNPJ 00.000.000/0001-91, incluindo os sócios.”
• “Verifique estes 30 CNPJs e me diga quais estão baixados ou inaptos.”
• “Quantos créditos eu ainda tenho? Quanto custaria buscar mais 3 páginas dessa lista?”

Créditos e limites

• O MCP usa os mesmos créditos da sua conta no site e na API REST, com as mesmas regras de cobrança.
• Toda resposta paga traz credits_used e credits_remaining, para a IA informar o gasto a você.
• Se o saldo acabar no meio de uma busca, o resultado é limitado ao que os créditos cobrem — nada é cobrado além do saldo.
• Limite de 60 requisições por minuto por conta. A busca com IA tem limite próprio por minuto.
• Dica: peça à IA para confirmar o custo antes de buscar várias páginas.

Erros

Erros de autenticação e de protocolo voltam como erro JSON-RPC; falhas de uma ferramenta (filtro inválido, saldo insuficiente) voltam como resultado com isError: true, para a IA explicar o problema na conversa.

Exemplo de resposta para uma conta sem plano ativo:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32003,
    "message": "MCP access requires an active CNPJLeads plan. Subscribe or buy a plan to enable it.",
    "data": { "error_code": "active_plan_required", "upgrade_url": "https://cnpjleads.com/pt-br/preco" }
  }
}

Segurança

• O token dá acesso aos seus créditos. Não o compartilhe nem o publique em repositórios de código; prefira variáveis de ambiente ou o campo seguro do VS Code.
• O token não expira: trate-o como uma senha e guarde-o apenas em locais seguros.
• Todas as ferramentas são somente leitura e cada chamada é registrada para auditoria.
• Conexões só por HTTPS. Requisições de navegadores de sites não autorizados são bloqueadas.

Detalhes do protocolo

• Transporte Streamable HTTP, sem estado: cada POST em /api/mcp é independente e retorna application/json. Não é preciso guardar sessão.
• Versões suportadas: 2025-06-18, 2025-03-26, 2024-11-05. O servidor responde com a versão pedida pelo cliente quando suportada.
• Capacidades: tools, prompts e resources (lista vazia). GET e DELETE retornam 405 (não há stream iniciado pelo servidor).
• Resultados de ferramentas trazem content (texto JSON) e structuredContent (objeto), além das anotações readOnlyHint.

Fluxo típico:

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0"}}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","serverInfo":{"name":"cnpjleads",...},"capabilities":{"tools":{...}}}}
→ {"jsonrpc":"2.0","method":"notifications/initialized"}            ← HTTP 202
→ {"jsonrpc":"2.0","id":2,"method":"tools/list"}
→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"find_cnae","arguments":{"term":"padaria"}}}
← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"..."}],"structuredContent":{...},"isError":false}}

Perguntas frequentes