Pearch

Pearch.ai MCP

Serveur MCP pour Pearch.AI : recherche en langage naturel sur des personnes et des entreprises/leads (B2B). Utilisez-le depuis Claude, Cursor, VS Code ou tout client compatible MCP.

Évaluation des outils de sourcing pour le recrutement par IA selon la préférence humaine

Outils

Outil	Description
search_people	Recherche de personnes avec une requête en langage naturel query ou des critères structurés search_requirements. Prend en charge les types de recherche fast/pro/superfast, la révélation des contacts et les filtres de contacts, l'actualisation des profils en temps réel, les insights, ainsi que la pagination et les relances basées sur un thread.
search_company_leads	Trouvez des entreprises et les leads/contacts qu'elles contiennent (B2B). Exemple : entreprise « startups IA à SF, 50–200 employés » + leads « CTO et responsables ingénierie », avec des messages de prospection personnalisés en option.
get_profile	Recherchez et enrichissez une personne unique par slug LinkedIn ou e-mail (révélation des contacts, actualisation en temps réel, enrichissement GitHub).
get_user_info	Informations de l'utilisateur authentifié : e-mail, crédits restants, formule tarifaire. Gratuit.

Recherche structurée de personnes

Passez search_requirements à search_people lorsque vous disposez déjà d'une liste de critères :

{
  "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 : texte requis, non vide. Gardez chaque critère court et autonome.
• must_have : true pour les critères obligatoires, false pour les préférences souhaitables (valeur par défaut).

La liste doit contenir au moins une exigence. query est facultatif lorsque vous utilisez search_requirements ; si les deux sont fournis, l'API donne la priorité à search_requirements. Voir le contrat de l'API de recherche Pearch.

Les deux entrées prennent en charge les mêmes options de recherche : type de recherche, insights et scoring, actualisation des profils, révélation des contacts et filtres, filtrage strict, résultats à faible confiance, budget de temps, pagination, champs de réponse, exclusions de profils et résultats masqués gratuits. Les restrictions liées au type de recherche sont les mêmes pour les deux entrées ; par exemple, superfast ne prend pas en charge les insights, le scoring des profils ni une fraîcheur élevée.

Pour la pagination, envoyez le thread_id renvoyé avec limit et éventuellement offset, en omettant query et search_requirements. Pour modifier les critères, démarrez une nouvelle recherche sans thread_id. Les appels existants avec query et les relances de thread sont toujours transmis comme avant ; l'API décide quels paramètres de relance elle accepte.

custom_filters n'est pas exposé par ce serveur MCP. Exprimez plutôt les critères dans query ou search_requirements.

Serveur distant (recommandé)

Le serveur hébergé se trouve à l'adresse https://mcp.pearch.ai/mcp et prend en charge deux schémas d'authentification simultanément :

OAuth (aucune gestion de clé)

Ajoutez le serveur sans aucun en-tête — les clients compatibles OAuth (Claude, Cursor, VS Code) découvrent le flux automatiquement et ouvrent une connexion Google. Connectez-vous avec le compte Google dont l'e-mail correspond à votre compte Pearch :

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

Vos recherches débitent des crédits sur votre propre compte Pearch. Si votre compte Pearch n'a pas encore de clé API, créez-en une d'abord dans le tableau de bord Pearch.ai.

Clé API

Passez la même clé API Pearch comme api.pearch.ai :

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

Utilisez test_mcp_key pour des résultats masqués (échantillons) — aucune inscription requise.

Installation locale (stdio)

Nécessite Python 3.10+ et 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 manuellement sous 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

Remplacez test_mcp_key par votre clé du tableau de bord pour obtenir des résultats complets.

Exécuter votre propre serveur HTTP

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

État de santé : GET /health ou /healthcheck (indique le mode d'authentification).

Variables d'environnement

Variable	Valeur par défaut	Rôle
PEARCH_MCP_AUTH	api_key	oauth | api_key | none. En mode oauth, les bearers de clé API bruts sont toujours acceptés (double authentification).
PEARCH_MCP_BASE_URL	http://localhost:8000	URL publique de ce serveur. Les métadonnées OAuth, l'audience des jetons et l'URI de redirection /auth/callback en dérivent tous.
PEARCH_MCP_GOOGLE_CLIENT_ID / PEARCH_MCP_GOOGLE_CLIENT_SECRET	—	Client Google OAuth 2.0 de type application Web (enregistrez <base_url>/auth/callback comme URI de redirection). Requis en mode oauth.
PEARCH_MCP_INTERNAL_TOKEN	—	Secret partagé pour la correspondance interne e-mail→clé API et la signature de la source des requêtes. Requis en mode oauth et pour une attribution MCP vérifiée avec des clés API. Doit correspondre au MCP_INTERNAL_TOKEN du backend ; ne jamais le distribuer aux utilisateurs finaux.
PEARCH_MCP_OAUTH_STORE	disk	redis conserve l'état OAuth (enregistrements de clients, jetons — chiffrés) dans Redis afin qu'il survive aux redémarrages et permette plus d'une réplique.
PEARCH_MCP_OAUTH_REDIS_HOST / REDIS_ENDPOINT, REDIS_PORT, PEARCH_MCP_OAUTH_REDIS_DB, REDIS_PASSWORD	—, 6379, 4, —	Connexion Redis pour le stockage OAuth.
PEARCH_MCP_ALLOWED_CLIENT_REDIRECT_URIS	liste intégrée	Motifs fnmatch séparés par des virgules pour les URI de redirection des clients MCP (* = n'importe lequel).
PEARCH_MCP_TOKEN_CACHE_TTL_S	300	Durée de vie du cache des identités vérifiées ; également le délai de révocation.
PEARCH_API_URL	https://api.pearch.ai	Base de l'API Pearch (les base_url par appel la remplacent).
PEARCH_API_KEY	test_mcp_key	Clé de secours pour l'utilisation stdio/locale.
MCP_DISABLE_AUTH	—	1 équivaut à PEARCH_MCP_AUTH=none (développement local uniquement).

Les requêtes d'outils vers l'API Pearch incluent X-Pearch-Source: mcp sur les appels POST et GET, y compris la recherche de personnes, la recherche d'entreprises/leads, la pagination et l'enrichissement de profils. Le serveur hébergé envoie également X-Pearch-Source-Signature lorsque le secret interne est configuré et que l'origine de destination correspond à PEARCH_API_URL. Le HMAC lie le justificatif bearer, la méthode, le chemin décodé plus la requête brute, le corps et l'horodatage. Le backend accepte les signatures dans un délai de 300 secondes, les horloges des serveurs doivent donc être synchronisées. Les valeurs base_url fournies par l'appelant sur d'autres origines ne reçoivent aucune signature.

Le backend enregistre le trafic MCP vérifié comme api_calls.request_source pour l'analytique et l'historique DevAdmin. Un simple en-tête de source ne suffit pas. Le trafic MCP auto-hébergé non signé utilisant des clés API reste api ; les clients OAuth authentifiés et autorisés sont reconnus sans en-têtes. Déployez la signature avant d'activer la journalisation des sources du backend, après avoir appliqué sa migration de base de données. Les backends plus anciens ignorent les en-têtes. L'authentification, l'attribution des comptes et la facturation restent inchangées.

En mode oauth, l'ingress/proxy inverse doit router le hôte entier vers le serveur, pas seulement /mcp : le flux ajoute /.well-known/oauth-*, /authorize, /token, /register, /revoke, /consent et /auth/callback.

Développement

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

Politique de confidentialité

Politique de confidentialité de Pearch.AI : https://pearch.ai/privacy-policy — couvre la collecte des données, leur utilisation, leur stockage, le partage avec des tiers, la conservation et les informations de contact. Suppression des données / désinscription : https://pearch.ai/opt-out. Conditions d'utilisation : https://pearch.ai/tos.

Support

• Ouvrir un ticket
• f@pearch.ai

Licence

MIT — voir LICENSE.