Generect MCP

O Generect MCP conecta sua base de leads ao vivo diretamente a modelos de IA como OpenAI ou Claude, sem exportações ou atrasos. Ele transmite dados de contato enriquecidos e atualizados (cargos, firmografia, sinais) diretamente nos prompts, permitindo que LLMs personalizem, pontuem e recomendem leads automaticamente em tempo real.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP da API Generect

Dados de leads e empresas B2B para agentes de IA — busca, pré-visualização, enriquecimento, consulta de e-mails e telefones pela API Generect.

Construído para que um agente trabalhe sem queimar o saldo do cliente: dimensionar uma audiência é gratuito, cada ferramenta informa antecipadamente se custa dinheiro, e cada resposta reporta o que foi efetivamente cobrado.

Obtenha sua Chave de API

Cadastre-se e obtenha sua chave de API em https://app.generect.com

Servidor MCP Remoto (OAuth - Recomendado)

Este servidor MCP implementa autorização OAuth 2.1 conforme especificado pelo Model Context Protocol.

Use nosso servidor MCP hospedado com qualquer cliente MCP compatível com OAuth:

{
  "mcpServers": {
    "generect": {
      "url": "https://mcp.generect.com/mcp",
      "type": "http"
    }
  }
}

Ao conectar pela primeira vez, o cliente iniciará um fluxo OAuth:

Você será redirecionado para a página de autorização
Insira seu token de API Generect de app.generect.com
Autorize o cliente a acessar sua API
O cliente recebe um token de acesso e pode usar as ferramentas MCP

Endpoints OAuth

Endpoint	Descrição
`/.well-known/oauth-protected-resource`	Metadados de Recurso Protegido (RFC 9728)
`/.well-known/oauth-authorization-server`	Metadados do Servidor de Autorização (RFC 8414)
`/.well-known/jwks.json`	Conjunto de Chaves JSON Web para verificação de token
`/oauth/authorize`	Endpoint de autorização (login + consentimento)
`/oauth/token`	Endpoint de token
`/oauth/register`	Registro Dinâmico de Clientes (RFC 7591)

Chave de API direta (sem OAuth)

Se o seu cliente MCP não conseguir concluir o fluxo OAuth, você pode passar a chave de API diretamente pelo cabeçalho Authorization. O servidor aceita qualquer um dos seguintes:

Authorization: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
Authorization: Token YOUR_API_KEY
Authorization: Bearer Token YOUR_API_KEY   (legacy)

Exemplo para mcp-remote:

{
  "mcpServers": {
    "generect": {
      "command": "mcp-remote",
      "args": [
        "https://mcp.generect.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Instalação Local (Alternativa)

Para desenvolvimento local ou quando OAuth não for necessário:

Requisitos: Node >= 18
Configure o ambiente:

GENERECT_API_BASE=https://api.generect.com
GENERECT_API_KEY=Token <api-key>
GENERECT_TIMEOUT_MS=300000
JWT_SIGNING_KEY=<your-secret-key-for-jwt-signing>
TOKEN_ENCRYPTION_KEY=<32-byte-hex-key-for-token-encryption>

Desenvolvimento local (opcional)

npm install
npm run dev:http

Compilar e iniciar (servidor stdio)

npm run build && npm start

Registro de Logs

O servidor emite uma linha de log JSON estruturada por evento para stderr (stdout é reservado para o protocolo MCP stdio). O registro de metadados está ativo por padrão; defina MCP_LOG=0 para desativá-lo completamente.

Privacidade — payloads são mascarados por padrão. Payloads de requisição/resposta podem conter dados pessoais de prospects (nomes, domínios de empresas, e-mails gerados). Por padrão, esses valores não são registrados literalmente: cada um é reduzido a um marcador de forma não identificável (ex.: "first_name": "<str:4>"), para que você possa ver quais campos foram enviados sem registrar os dados em si. Defina MCP_LOG_PAYLOADS=1 para registrar payloads literalmente — destinado a depuração de curta duração, com consentimento do titular dos dados.

Eventos:

`event`	Quando	Campos-chave
`tool_call`	LLM invoca uma ferramenta	`reqId`, `tool`, `input` (mascarado a menos que `MCP_LOG_PAYLOADS=1`)
`api_request`	Chamada de saída para a API Generect	`url`, `method`, `body` (mascarado a menos que `MCP_LOG_PAYLOADS=1`; nunca o token)
`api_response`	API Generect respondeu	`url`, `status`, `ms`
`tool_result`	Resultado retornado ao LLM	`reqId`, `tool`, `ms`, `output` (mascarado a menos que `MCP_LOG_PAYLOADS=1`)
`tool_error` / `api_error`	Falha	`reqId`/`url`, `error`, `ms`

reqId correlaciona um tool_call com seu tool_result. Defina MCP_DEBUG=1 para saída adicional detalhada.

O servidor hospedado roda sob PM2 (não Docker). Veja os logs no host com:

pm2 logs generect-mcp                                # live
pm2 logs generect-mcp --err                          # errors only
grep tool_call ~/.pm2/logs/generect-mcp-out.log      # only LLM tool inputs

Modo de teste

A API da Generect seleciona o modo real ou de teste pela chave, não pela URL — portanto, este servidor não precisa de implantação separada nem de ferramenta extra. Cole uma chave de teste (test_…, criada em app.generect.com/settings/api) na mesma configuração e cada ferramenta responde com dados fictícios, na velocidade em que o endpoint real roda, mostrando o preço que a chamada real custaria, sem cobrar nada.

{
  "mcpServers": {
    "generect": {
      "command": "mcp-remote",
      "args": ["https://mcp.generect.com/mcp", "--header", "Authorization: Bearer test_YOUR_TEST_KEY"]
    }
  }
}

Todo resultado de uma chave de teste carrega test_mode: true e um aviso informando ao modelo que as pessoas são fictícias. Isso não é decoração. Um agente que recebe doze prospects inventados sem marcador irá resumi-los como doze prospects, e a pessoa que lê o resumo não tem como saber — a falha mais provável do modo de teste em um canal de agente é um relatório confiante sobre pessoas que não existem. O marcador é adicionado centralmente, então nenhuma ferramenta pode esquecê-lo.

Consulte Modo de teste para as entradas mágicas que forçam um 402, um 429 ou um timeout sob demanda.

Ferramentas

Cada ferramenta declara em sua própria descrição se é gratuita ou cobrável, e cada resposta carrega um bloco cost com o valor que a API efetivamente cobrou. As ferramentas aceitam timeout_ms.

Gratuitas — comece aqui

Ferramenta	O que faz
`count_leads`	Quantos leads correspondem a um ICP + quanto custa o próximo passo às suas tarifas. Execute antes de `search_leads`.
`count_companies`	O mesmo, para empresas.
`get_balance`	Saldo, preços reais por operação desta conta, além de `include_usage` opcional (gasto por operação) e `include_token_analytics` (qual token fez quais chamadas).
`get_bulk_job`	Consultar um job em lote (o trabalho foi cobrado no momento do envio).
`manage_webhooks`	Listar/criar/atualizar/excluir/testar endpoints de webhook.
`health`	Verificação de atividade + credenciais contra um endpoint gratuito. Seguro para monitores.

Cobráveis

Ferramenta	Cobrança
`search_leads`	por linha retornada
`search_companies`	por linha retornada
`preview_leads`	por linha retornada (forma mais barata de ver pessoas reais); `count_only: true` é gratuito e é uma segunda opinião sobre `count_leads`, já que pré-visualização e busca em cache são índices diferentes
`enrich_lead` / `get_lead_by_url`	por registro encontrado
`resolve_profile`	por perfil resolvido — a chamada mais barata aqui; uma referência não resolvível é gratuita
`enrich_company`	por registro encontrado
`generate_email`	por e-mail válido encontrado
`validate_email`	por e-mail enviado — cada endereço, qualquer que seja o veredito
`find_phone`	por telefone encontrado — a operação mais cara aqui
`start_bulk_job`	por registro, reservado no momento do envio

database vs realtime

Cada busca/enriquecimento roda contra o banco de dados em cache (sub-segundo, mais barato, contagens gratuitas) ou uma consulta ao vivo no LinkedIn (5–60s, mais caro, contagens cobráveis, todos os filtros). As ferramentas aceitam mode: "auto" | "database" | "realtime":

auto (padrão) tenta o caminho barato e escala somente se a API disser que um filtro passado não existe lá. A escalada é reportada na resposta, nunca silenciosa.
database nunca escala: se um filtro não for suportado, você recebe um erro, não uma conta maior.
Contagem é a exceção — uma contagem em tempo real custa dinheiro, então count_leads / count_companies se recusam a executar uma a menos que você peça mode: "realtime" explicitamente. Elas informam quais filtros forçaram a escolha.

Vocabulários de filtros — leia-os, não adivinhe

Medidos contra a API ao vivo, os endpoints de busca v1 validam seus filtros de forma inconsistente:

Filtro	Valor desconhecido
`locations`, `company_headcounts`, `company_types`	HTTP 400 nomeando o campo
`company_industries`, `seniorities`	aceito — 0 resultados, $0, sem erro

Essa segunda linha é a perigosa. company_industries: ["Fintech"] não é uma indústria do LinkedIn e retorna como uma contagem perfeitamente bem-sucedida de zero, o que parece exatamente "essa audiência não existe".

Então o servidor verifica esses valores por conta própria, antes de enviar qualquer coisa:

uma indústria, faixa de headcount ou tipo de empresa desconhecido é recusado localmente com os nomes válidos mais próximos (Fintech → Financial Services, 50-200 → 51-200), e nada é enviado ou cobrado;
um valor meramente com erro de grafia ou capitalização é corrigido (software development → Software Development) — a correspondência é exata, então enviá-lo como digitado teria retornado zero;
uma senioridade ou função desconhecida é um aviso, não uma recusa: o mecanismo corresponde de forma flexível (Owner encontra pessoas mesmo que o rótulo canônico seja Owner / Partner);
allow_unlisted_values: true substitui a verificação se o snapshot deste servidor estiver desatualizado em relação à API.

Os vocabulários completos são expostos como recursos, para que um cliente possa lê-los uma vez e parar de adivinhar:

generect://vocabulary/industries        434 names, with parents
generect://vocabulary/seniorities
generect://vocabulary/functions         (realtime only)
generect://vocabulary/company-types
generect://vocabulary/headcounts
generect://vocabulary/follower-ranges   (realtime only)
generect://account/pricing              this account's real per-operation prices
generect://account/balance              balance and month-to-date usage

Eles são regenerados a partir dos próprios dados de filtro do backend com node scripts/gen-vocabulary.mjs <api_parser checkout> — nunca editados manualmente.

Prompts

Prompts de fluxo de trabalho acompanham o servidor e aparecem como comandos de barra em clientes que os suportam: size_an_audience, build_prospect_list, enrich_my_list, spend_report. Cada um começa pela etapa gratuita.

Limite de gastos

Um limite de linhas limita resultados, não dinheiro. Qualquer chamada cujo pior caso exceda MCP_MAX_SPEND_PER_CALL (padrão $5) é recusada com o valor exato e precisa ser repetida com confirm_spend_usd definido para pelo menos esse valor. Isso é verificado antes de start_bulk_job enviar, porque um job em lote reserva todo o seu custo no momento do envio e não pode ser desfeito.

Fluxo seguro para orçamento

count_leads (free)  →  preview_leads (cheap)  →  search_leads (per row)
                                              →  generate_email on the ids you kept

get_balance antes e depois de um lote fornece um valor exato de gasto para reportar.

Habilidade do agente

Ferramentas dão ao agente a capacidade de chamar a Generect; uma habilidade dá a ele o procedimento. skills/generect-lead-workflows documenta os fluxos acima para que um agente autônomo os siga sem precisar ser instruído toda vez:

npx skills add generect/generect_mcp --skill generect-lead-workflows

Consulte skills/README.md. Processo de release e a lista completa de lugares onde uma versão precisa chegar: RELEASING.md.

Integração com Cursor (trecho de settings.json)

{
  "mcpServers": {
    "generect-liveapi": {
      "command": "node",
      "args": ["./node_modules/tsx/dist/cli.mjs", "src/server.ts"],
      "env": {
        "GENERECT_API_BASE": "https://api.generect.com",
        "GENERECT_API_KEY": "Token YOUR_API_KEY",
        "GENERECT_TIMEOUT_MS": "300000"
      }
    }
  }
}

Configuração do Claude Desktop (MCP)

Adicione em ~/.claude/claude_desktop_config.json (ou via UI → MCP Servers). Recomendado: execute via npx para que os usuários não instalem nada globalmente.

{
  "mcpServers": {
    "generect-api": {
      "command": "npx",
      "args": ["-y", "generect-ultimate-mcp@latest"],
      "env": {
        "GENERECT_API_BASE": "https://api.generect.com",
        "GENERECT_API_KEY": "Token YOUR_API_KEY",
        "GENERECT_TIMEOUT_MS": "300000",
        "MCP_DEBUG": "0"
      }
    }
  }
}

Nota para macOS: Se o Claude mostrar "spawn npx ENOENT" ou iniciar um Node mais antigo via nvm, defina command para o caminho absoluto do npx e/ou substitua o PATH:

{
  "command": "/usr/local/bin/npx",
  "env": { "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" }
}

Alternativa sem npx:

npm i -g generect-ultimate-mcp

Depois use:

{ "command": "/usr/local/bin/generect-mcp", "args": [] }

Implantação (produção, PM2)

O servidor hospedado (https://mcp.generect.com) roda sob PM2 como mcp_user no host, com nginx na frente (TLS), definido por ecosystem.config.cjs.

Implantações são automáticas. Uma execução verde de ci em main aciona deploy-prod.yml, que alcança o host via SSH com uma chave que pode executar exatamente uma coisa — deploy/remote-deploy.sh — e verifica o endpoint público depois. O script:

apenas leva o host ao topo de main (nunca um commit mais antigo);
recusa implantar sobre edições não commitadas no host, ou iniciar uma segunda instância do pm2;
reinicia com o ambiente que o pm2 já possui (reload, não --update-env);
faz rollback automaticamente para o que estava rodando se o novo build não subir com a versão esperada em 60 s.

deploy/sandbox-test.sh exercita tudo isso contra uma cópia descartável do repositório com seu próprio pm2 — execute após alterar o script de implantação. A configuração única do host é deploy/bootstrap-chronos.sh (como root).

Apenas instância única. O estado OAuth (clientes registrados, códigos de autorização) e as sessões MCP são mantidos em memória, então o servidor deve rodar como uma única instância. Escalar horizontalmente requer um armazenamento compartilhado (ex.: Redis) primeiro — veja ecosystem.config.js.

Segredos obrigatórios (falha fechada). Em produção (NODE_ENV=production) o servidor se recusa a iniciar a menos que JWT_SIGNING_KEY esteja definido com um valor forte e não padrão; ele nunca recorre a um padrão codificado ou a uma chave efêmera. TOKEN_ENCRYPTION_KEY, se definido, deve ter exatamente 64 caracteres hexadecimais (32 bytes).

Docker

Docker é suportado para execuções locais/alternativas. Compile localmente:

docker build -t ghcr.io/generect/generect_mcp:local .

Execute o servidor em um contêiner (observação: os mesmos segredos de produção são obrigatórios — um padrão inseguro fará o contêiner sair na inicialização):

docker run --rm \
  -e NODE_ENV=production \
  -e GENERECT_API_BASE=https://api.generect.com \
  -e GENERECT_API_KEY="Token YOUR_API_KEY" \
  -e JWT_SIGNING_KEY="a-strong-random-secret" \
  -e TOKEN_ENCRYPTION_KEY="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" \
  -e OAUTH_BASE_URL=https://your-domain.com \
  -p 3000:3000 \
  ghcr.io/generect/generect_mcp:local

Remoto via SSH (avançado)

Alguns clientes MCP permitem iniciar o servidor via SSH, usando stdio na sessão SSH. Exemplo de configuração:

{
  "mcpServers": {
    "generect-remote": {
      "command": "ssh",
      "args": [
        "user@remote-host",
        "-T",
        "node",
        "/opt/generect_mcp/dist/server.js"
      ],
      "env": {
        "GENERECT_API_BASE": "https://api.generect.com",
        "GENERECT_API_KEY": "Token YOUR_API_KEY",
        "GENERECT_TIMEOUT_MS": "300000"
      }
    }
  }
}

Auxiliares de teste local

Todos os três usam apenas chamadas de API gratuitas por padrão — um teste de fumaça nunca deve cobrar silenciosamente quem o executa.

Verificação de saúde (conta, catálogo de preços, contagem gratuita em cache):

npm run health -- <api-key>

Quais filtros o índice gratuito em cache suporta agora (apenas contagens gratuitas):

npm run probe -- <api-key>

Chamar ferramentas via um cliente MCP local. Ferramentas gratuitas por padrão; --paid adiciona uma busca de 3 linhas e uma consulta de e-mail, e a execução imprime o que foi gasto:

npm run mcp:client -- <api-key>
npm run mcp:client -- <api-key> --paid

Notas de segurança

Tokens OAuth são JWTs assinados pelo servidor e contêm seu token de API criptografado
Criptografia de tokens usa AES-256-GCM com uma chave de TOKEN_ENCRYPTION_KEY (ou derivada de JWT_SIGNING_KEY)
Segredos com falha fechada — em produção, o servidor se recusa a iniciar com um JWT_SIGNING_KEY ausente ou com padrão conhecido, e nunca publica material de chave simétrica no JWKS
Tokens limitados e renováveis — tokens de acesso expiram (padrão 30 dias, ACCESS_TOKEN_TTL_SECONDS) e são renovados via uma concessão refresh_token; tokens de atualização são rotacionados no uso e revogáveis em POST /oauth/revoke (RFC 7009). Tokens emitidos antes desta mudança permanecem válidos (sem reautenticação forçada)
PKCE é obrigatório para todos os fluxos de código de autorização (método S256) e é revalidado tanto no POST de consentimento quanto no redirecionamento inicial — um código interceptado por um aplicativo malicioso que reivindica o mesmo esquema de URI é inútil sem o verificador
Registro Dinâmico de Clientes permite que qualquer cliente MCP se registre, mas agora é limitado por IP (MCP_REGISTER_RATE_MAX, padrão 60/hora) e o armazenamento de clientes é limitado (MCP_MAX_CLIENTS, padrão 5000, evicção LRU que nunca remove um cliente em uso)
URIs de redirecionamento: abertas por padrão, então qualquer cliente pode conectar (MCP_REDIRECT_POLICY=open). Aceitas: qualquer URL https, http apenas em endereços loopback/privados, e o esquema de URI de uso privado de um aplicativo (cursor://…, vscode://…, com.example.app:/cb — RFC 8252 §7.1). Recusadas independentemente da política: http em texto claro para um host público, #fragments, credenciais incorporadas, URIs excessivamente longas e esquemas executáveis por navegador (javascript:, data:, file:, …) — essa URI é navegada a partir da nossa própria origem, então seriam XSS. Callbacks de loopback correspondem a tudo exceto a porta (RFC 8252 §7.3), já que o listener de um aplicativo nativo recebe uma porta efêmera. Defina MCP_REDIRECT_POLICY=strict para voltar à lista de permissões de primeira parte (*.generect.com, claude.ai, linear.app, mais MCP_ALLOWED_REDIRECT_DOMAINS / MCP_ALLOWED_REDIRECT_SCHEMES)
Buscas de metadados protegidas contra SSRF — o fluxo de documento de metadados de ID de cliente (MCP_ENABLE_CIMD, ativado por padrão) busca apenas URLs https que resolvem exclusivamente para IPs públicos, sem seguir redirecionamentos, com timeout rígido e limite de tamanho de resposta (bloqueia alvos loopback / RFC1918 / link-local / metadados de nuvem)
Validação de token falha fechada — se a Generect não puder confirmar um token durante o login (erro upstream), o servidor se recusa a emitir um token de acesso em vez de assumir validade
Fixação de público + algoritmo garante que os tokens sejam usados apenas com este servidor MCP e apenas com o algoritmo de assinatura esperado

Configuração (variáveis de ambiente relevantes para segurança)

Var	Padrão	Efeito
`ACCESS_TOKEN_TTL_SECONDS`	`2592000` (30d)	Vida útil do token de acesso
`REFRESH_TOKEN_TTL_SECONDS`	`7776000` (90d)	Vida útil do token de atualização
`MCP_MAX_CLIENTS`	`5000`	Limite no armazenamento de clientes DCR em memória
`MCP_REGISTER_RATE_MAX`	`60`	Máx. de chamadas `/oauth/register` por IP por janela
`MCP_REGISTER_RATE_WINDOW_MS`	`3600000` (1h)	Janela de limite de taxa
`MCP_ENABLE_CIMD`	`true`	Permitir ID de cliente como URL de metadados (protegido contra SSRF)
`MCP_REDIRECT_POLICY`	`open`	`open` = qualquer cliente pode registrar seu callback; `strict` = apenas lista de permissões de primeira parte
`MCP_ALLOWED_REDIRECT_DOMAINS`	—	Hosts de redirecionamento adicionais permitidos, apenas `strict` (separados por vírgula)
`MCP_ALLOWED_REDIRECT_SCHEMES`	—	Esquemas de URI de uso privado adicionais permitidos, apenas `strict` (separados por vírgula, ex.: `cursor,vscode`)
`MCP_ALLOW_ANY_HTTPS_REDIRECT`	—	Legado: abre callbacks https sob `strict` (implícito por `open`)

Privacidade de logs — cargas de prospects são removidas dos logs por padrão (MCP_LOG_PAYLOADS=1 para optar por incluir)

Consentimento intermediado: qual UI do produto aprova a conexão

/oauth/authorize não solicita senha. Ele encaminha para uma página no produto onde o usuário já está conectado, e essa página envia um token de API recém-cunhado de volta para /oauth/broker. Duas variáveis de ambiente decidem qual página é essa, e elas devem ser alteradas juntas:

Var	Efeito
`MCP_CONSENT_URL`	Para onde `/oauth/authorize` redireciona o usuário (`…/authorize/mcp?handoff=…&mcp=…`)
`MCP_CONSENT_ORIGIN`	O único `Origin` permitido a chamar `/oauth/broker`. Padrão: a origem de `MCP_CONSENT_URL` — mas produção define explicitamente em `.env`, então o padrão não salva você

Mover o consentimento de um host para o outro editando apenas MCP_CONSENT_URL faz o intermediário recusar a nova página com 403 {"error":"forbidden","error_description":"Origin not allowed to broker consent."}, depois que o usuário já clicou em Aprovar. Altere ambas as linhas e então comprove:

# expect 400 invalid_handoff (origin accepted), NOT 403 forbidden
curl -s -X POST https://mcp.generect.com/oauth/broker \
  -H 'Content-Type: application/json' -H "Origin: <the new consent origin>" \
  -d '{"handoff":"nonexistent-probe","deny":true}'

CORS não é o controle aqui — o servidor reflete qualquer Origin (autenticação bearer, sem cookies), então um preflight bem-sucedido não prova nada sobre o intermediário.

Implantando em produção

mcp.generect.com executa pm2, não Docker (.github/workflows/deploy-prod.yml é o caminho Docker não utilizado). Instância única, sempre: estado OAuth e sessões MCP vivem em memória, então um segundo worker dividiria o cérebro da autenticação.

ssh root@chronos                      # 65.21.69.164
su - mcp_user && source ~/.nvm/nvm.sh # node via nvm
cd ~/generect_mcp
cp -r dist dist.bak.$(date +%H%M%S)   # what previous deploys did; keeps a rollback
git pull && npm ci && npm run build
$EDITOR .env                          # consent vars, redirect policy
pm2 reload generect-mcp && pm2 list   # version column should show the new one

Então verifique de fora da máquina — pm2 list mostrando online não é evidência de que o novo comportamento está ativo:

curl -s https://mcp.generect.com/health
curl -s -o /dev/null -w '%{redirect_url}\n' \
  "https://mcp.generect.com/oauth/authorize?client_id=<id>&redirect_uri=…&response_type=code&code_challenge=…&code_challenge_method=S256"