Pearch

Pearch.ai MCP

Servidor MCP para o Pearch.AI: busca em linguagem natural por pessoas e empresas/leads (B2B). Use-o a partir do Claude, Cursor, VS Code ou qualquer cliente compatível com MCP.

Avaliando Ferramentas de Sourcing de Recrutamento com IA por Preferência Humana

Ferramentas

Ferramenta	Descrição
search_people	Busca de pessoas com uma query em linguagem natural ou search_requirements estruturado. Suporta tipos de busca fast/pro/superfast, revelação de contatos e filtros de contato, atualização de perfil em tempo real, insights e paginação/continuações baseadas em thread.
search_company_leads	Encontre empresas e leads/contatos dentro delas (B2B). Exemplo: empresa "startups de IA em SF, 50–200 funcionários" + leads "CTOs e gerentes de engenharia", com mensagens de abordagem personalizadas opcionais.
get_profile	Consulte e enriqueça uma única pessoa por slug do LinkedIn ou e-mail (revelação de contato, atualização em tempo real, enriquecimento via GitHub).
get_user_info	Informações do usuário autenticado: e-mail, créditos restantes, plano de preços. Gratuito.

Busca estruturada de pessoas

Passe search_requirements para search_people quando você já tiver uma lista de critérios:

{
  "search_requirements": [
    {
      "search_requirement": "Software engineer with 5+ years of Python experience",
      "must_have": true
    },
    {
      "search_requirement": "Experience at a fintech company",
      "must_have": false
    }
  ],
  "search_type": "fast",
  "limit": 10,
  "insights": true,
  "reveal_emails": true
}

• search_requirement: obrigatório, texto não vazio. Mantenha cada critério curto e autossuficiente.
• must_have: true para critérios obrigatórios, false para preferências desejáveis (o padrão).

A lista deve conter pelo menos um requisito. query é opcional ao usar search_requirements; se ambos forem fornecidos, a API dá precedência a search_requirements. Consulte o contrato da API de busca do Pearch.

Ambas as entradas suportam as mesmas opções de busca: tipo de busca, insights e pontuação, atualização de perfil, revelação de contatos e filtros, filtragem estrita, resultados de baixa confiança, limite de tempo, paginação, campos de resposta, exclusões de perfil e resultados mascarados gratuitos. As restrições de tipo de busca são as mesmas para ambas as entradas; por exemplo, superfast não suporta insights, pontuação de perfil ou alta atualidade.

Para paginação, envie o thread_id retornado com limit e, opcionalmente, offset, omitindo query e search_requirements. Para alterar os critérios, inicie uma nova busca sem thread_id. Chamadas existentes de query e continuações de thread ainda são encaminhadas como antes; a API decide quais parâmetros de continuação aceita.

custom_filters não é exposto por este servidor MCP. Expresse os critérios em query ou search_requirements.

Servidor remoto (recomendado)

O servidor hospedado fica em https://mcp.pearch.ai/mcp e suporta dois esquemas de autenticação ao mesmo tempo:

OAuth (sem gerenciamento de chaves)

Adicione o servidor sem nenhum cabeçalho — clientes compatíveis com OAuth (Claude, Cursor, VS Code) descobrem o fluxo automaticamente e abrem um login do Google. Faça login com a conta do Google cujo e-mail corresponde à sua conta Pearch:

claude mcp add --transport http pearch https://mcp.pearch.ai/mcp

Suas buscas debitam créditos da sua própria conta Pearch. Se sua conta Pearch ainda não tiver uma chave de API, crie uma primeiro no Painel do Pearch.ai.

Chave de API

Passe a mesma chave de API do Pearch como api.pearch.ai:

{
  "mcpServers": {
    "Pearch.ai": {
      "url": "https://mcp.pearch.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PEARCH_API_KEY}"
      }
    }
  }
}

Use test_mcp_key para resultados mascarados (de amostra) — sem necessidade de cadastro.

Instalação local (stdio)

Requer Python 3.10+ e pip install -r requirements.txt (ou pip install fastmcp).

Claude Desktop / Claude Code

fastmcp install claude-desktop pearch_mcp.py --env PEARCH_API_KEY=test_mcp_key

Ou manualmente em mcpServers:

"Pearch.ai": {
  "command": "python",
  "args": ["/path/to/mcp_pearch/pearch_mcp.py"],
  "env": { "PEARCH_API_KEY": "test_mcp_key" }
}

Cursor

fastmcp install cursor pearch_mcp.py --env PEARCH_API_KEY=test_mcp_key

Substitua test_mcp_key pela chave do seu painel para obter resultados completos.

Executando seu próprio servidor HTTP

uvicorn pearch_mcp:app --host 0.0.0.0 --port 8000

Saúde: GET /health ou /healthcheck (informa o modo de autenticação).

Variáveis de ambiente

Variável	Padrão	Finalidade
PEARCH_MCP_AUTH	api_key	oauth | api_key | none. No modo oauth, portadores de chave de API brutos ainda são aceitos (autenticação dupla).
PEARCH_MCP_BASE_URL	http://localhost:8000	URL pública deste servidor. Os metadados OAuth, a audiência do token e o URI de redirecionamento /auth/callback derivam todos dele.
PEARCH_MCP_GOOGLE_CLIENT_ID / PEARCH_MCP_GOOGLE_CLIENT_SECRET	—	Cliente de aplicativo Web do Google OAuth 2.0 (registre <base_url>/auth/callback como URI de redirecionamento). Obrigatório no modo oauth.
PEARCH_MCP_INTERNAL_TOKEN	—	Segredo compartilhado para mapeamento interno de e-mail→chave de API e assinatura da origem da requisição. Obrigatório no modo oauth e para atribuição MCP verificada com chaves de API. Deve corresponder ao MCP_INTERNAL_TOKEN do backend; nunca distribua aos usuários finais.
PEARCH_MCP_OAUTH_STORE	disk	redis mantém o estado OAuth (registros de clientes, tokens — criptografados) no Redis, para que sobreviva a reinicializações e permita mais de 1 réplica.
PEARCH_MCP_OAUTH_REDIS_HOST / REDIS_ENDPOINT, REDIS_PORT, PEARCH_MCP_OAUTH_REDIS_DB, REDIS_PASSWORD	—, 6379, 4, —	Conexão Redis para o armazenamento OAuth.
PEARCH_MCP_ALLOWED_CLIENT_REDIRECT_URIS	lista integrada	Padrões fnmatch separados por vírgula para URIs de redirecionamento de clientes MCP (* = qualquer).
PEARCH_MCP_TOKEN_CACHE_TTL_S	300	TTL do cache de identidade verificada; também o atraso de revogação.
PEARCH_API_URL	https://api.pearch.ai	Base da API do Pearch (substituições por chamada via base_url).
PEARCH_API_KEY	test_mcp_key	Chave de fallback para uso em stdio/local.
MCP_DISABLE_AUTH	—	1 é equivalente a PEARCH_MCP_AUTH=none (apenas desenvolvimento local).

As requisições de ferramentas à API do Pearch incluem X-Pearch-Source: mcp tanto em chamadas POST quanto GET, incluindo busca de pessoas, busca de leads de empresas, paginação e enriquecimento de perfil. O servidor hospedado também envia X-Pearch-Source-Signature quando o segredo interno está configurado e a origem de destino corresponde a PEARCH_API_URL. O HMAC vincula a credencial do portador, o método, o caminho decodificado mais a consulta bruta, o corpo e o timestamp. O backend aceita assinaturas dentro de 300 segundos, portanto os relógios dos servidores devem estar sincronizados. Valores de base_url fornecidos pelo chamador em outras origens não recebem assinatura.

O backend registra o tráfego MCP verificado como api_calls.request_source para análises e histórico do DevAdmin. Um cabeçalho de origem simples não é suficiente. O tráfego MCP auto-hospedado não assinado usando chaves de API permanece como api; clientes OAuth autenticados na lista de permissões são reconhecidos sem cabeçalhos. Implante a assinatura antes de habilitar o registro de origem no backend, após aplicar sua migração de banco de dados. Backends mais antigos ignoram os cabeçalhos. Autenticação, atribuição de conta e cobrança permanecem inalteradas.

No modo oauth, o proxy de entrada/reverso deve rotear o host inteiro para o servidor, não apenas /mcp: o fluxo adiciona /.well-known/oauth-*, /authorize, /token, /register, /revoke, /consent e /auth/callback.

Desenvolvimento

export PEARCH_API_KEY='test_mcp_key'   # or your key for full results
fastmcp dev inspector pearch_mcp.py

Política de Privacidade

Política de privacidade do Pearch.AI: https://pearch.ai/privacy-policy — abrange coleta de dados, uso, armazenamento, compartilhamento com terceiros, retenção e informações de contato. Exclusão de dados / opt-out: https://pearch.ai/opt-out. Termos de serviço: https://pearch.ai/tos.

Suporte

• Abrir uma issue
• f@pearch.ai

Licença

MIT — consulte LICENSE.