@nexhunter/mcp-server

Serveur MCP qui permet à un agent IA de déposer des CV et des fiches de besoin dans les centres d'import de votre espace Nexhunter.

L'agent dépose, il ne décide de rien : chaque document reste en attente de relecture dans Nexhunter. Aucun candidat n'entre dans un pipeline, aucune mission n'est publiée sans qu'un humain le valide dans l'application.

Cas d'usage typique : vos besoins et vos CV arrivent par mail ou sur un Drive, et un agent les dépose au fil de l'eau au lieu d'une saisie manuelle.

Prérequis

Une clé API de votre espace Nexhunter, portant les quatre capacités candidate:write, candidate:read, mission:write, mission:read.

La clé se crée dans Nexhunter : Paramètres → Gouvernance → Clés API. Le secret ne s'affiche qu'une seule fois, à la création — conservez-le dans votre gestionnaire de secrets avant de fermer la fenêtre. Si vous n'avez pas accès à cet écran, demandez la clé à un administrateur de votre organisation.

Deux façons de brancher un agent

1. Programme local (Claude Desktop, Claude Code, Cursor, VS Code…)

L'agent lance le serveur comme un programme sur votre machine et lui parle directement : rien n'est exposé sur le réseau. Il faut Node.js 20 ou plus sur la machine qui exécute l'agent. Ajoutez ce bloc à la configuration MCP de votre agent :

{
  "mcpServers": {
    "nexhunter": {
      "command": "npx",
      "args": ["-y", "@nexhunter/mcp-server"],
      "env": {
        "NEXHUNTER_API_URL": "https://<votre-espace>.nexhunter.com",
        "NEXHUNTER_API_KEY": "nxh_…"
      }
    }
  }
}

npx télécharge le paquet au premier lancement puis repart de son cache : il n'y a rien à installer, ni à mettre à jour à la main. Le -y évite une question de confirmation qui bloquerait un démarrage automatique. Cette configuration fonctionne à l'identique sur Windows, macOS et Linux.

Deux détails changent selon l'hôte : le fichier où ce bloc se dépose, et parfois le nom de la clé racine — VS Code attend servers là où Claude Desktop, Claude Code et Cursor attendent mcpServers. La documentation de votre espace Nexhunter détaille chaque hôte, avec le chemin du fichier et les pièges connus.

| Variable | Rôle | | --- | --- | | NEXHUNTER_API_URL | URL de votre espace, sans chemin — par exemple https://<votre-espace>.nexhunter.com | | NEXHUNTER_API_KEY | Le secret de la clé API, qui commence par nxh_ |

Les deux sont obligatoires : sans elles, le serveur s'arrête au démarrage avec un message d'erreur.

2. URL hébergée (n8n, agents cloud, orchestrateurs)

Pour les hôtes qui n'acceptent qu'une adresse web et ne peuvent pas lancer de programme local, Nexhunter héberge le même serveur derrière une URL :

https://mcp.nexhunter.com/mcp

L'authentification se fait par votre clé API, envoyée sur chaque requête dans l'en-tête Authorization: Bearer nxh_…. Il n'y a rien d'autre à configurer : la clé identifie votre organisation et porte vos capacités et quotas habituels.

Dans n8n : ajoutez le nœud MCP Client Tool à votre agent, renseignez l'URL ci-dessus comme Endpoint, choisissez le transport HTTP Streamable, et une authentification Bearer avec votre clé nxh_… comme secret. Les versions récentes de n8n sont requises pour le transport HTTP Streamable.

La disponibilité de ce point d'entrée peut dépendre de votre offre — en cas de doute, rapprochez-vous de votre contact Nexhunter.

Les quatre outils

| Outil | Fait quoi | | --- | --- | | import_candidate | Dépose un CV au format PDF ou Word (.docx), vers le vivier ou vers une mission déjà lancée | | import_mission | Dépose une fiche de besoin, en texte | | check_import | Donne l'état d'un lot déposé par cette clé | | read_workflow_rules | Renvoie les règles de dépôt complètes, rédigées à l'intention de l'agent |

Le serveur expose aussi une ressource nexhunter://workflow portant les mêmes règles. Certains hôtes MCP (n8n notamment) ne montrent jamais les ressources à l'agent — c'est précisément pourquoi read_workflow_rules existe en outil : faites-le appeler une fois avant le premier dépôt.

import_candidate n'accepte que des PDF et des Word .docx

Deux façons de fournir le fichier, exactement une des deux :

• contentBase64 : les octets du fichier d'origine, encodés en base64, avec un fileName portant l'extension correspondante (.pdf ou .docx) — c'est elle qui décide de la signature attendue.
• fileUrl : une adresse https publique d'où le serveur télécharge le fichier lui-même (5 Mo maximum). Préférable dès que le fichier est volumineux : l'agent n'a alors pas à faire transiter des mégaoctets d'encodage dans ses arguments d'outil.

Un texte, un résumé produit par l'agent ou une transcription sont refusés immédiatement : l'extraction de CV travaille sur le fichier lui-même. Sans le document d'origine (ou une URL vers lui), un candidat ne peut pas être déposé. Le .doc de Word 97-2003 n'est pas accepté — convertissez-le en .docx.

import_mission accepte du texte brut, lui : un besoin arrivé dans un corps de mail n'a pas de pièce jointe.

Ce que renvoie un outil

Chaque appel renvoie un résultat de forme constante — en texte et en contenu structuré (structuredContent), avec un schéma de sortie déclaré : un orchestrateur peut brancher la suite de son workflow sur data.batchId ou data.duplicate sans analyser du texte.

{ "ok": true,  "data": { "batchId": "…", "itemId": "…", "duplicate": false } }
{ "ok": false, "status": 403, "error": "Capacité manquante", "hint": "…" }

Sur une erreur, le champ hint dit à l'agent quoi faire, au moment exact où l'erreur survient — corriger, attendre, s'arrêter, ou signaler à un humain. Deux champs s'ajoutent quand le serveur les fournit : retryAfterSeconds (délai d'attente sur un 429) et details (par exemple le quota atteint sur un 409). Une panne réseau prend la même forme, avec status: 0 — jamais une exception brute qui casserait la lecture du résultat par l'agent.

Doublons

duplicate: true signifie que ce document était déjà présent dans votre espace. Ce n'est pas une erreur : c'est la protection qui évite qu'un même CV rentre deux fois parce qu'il apparaît dans deux mails. Le résultat le rappelle à l'agent dans son champ hint ; il doit passer au suivant.

Dans ce cas, batchId peut être absent de la réponse : cela arrive quand le document existait déjà dans un lot que cette clé n'a pas créé — déposé par une personne dans l'application, ou par une autre clé. Il n'y a alors rien à suivre avec check_import.

Codes d'erreur

| Code | Signification | Que faire | | --- | --- | --- | | 400 | Appel mal formé, ou contenu qui n'est pas un PDF ni un .docx | Corriger l'appel ; un nouvel essai à l'identique échouera | | 401 | Clé invalide, expirée ou révoquée | Vérifier la clé dans Nexhunter | | 403 | La clé n'a pas la capacité demandée | Ajouter les capacités manquantes au rôle de la clé | | 404 | Sur un dépôt vers une mission : ce missionId n'existe pas | Vérifier l'identifiant | | 409 | Le quota de votre organisation est atteint | S'arrêter ; ce n'est pas un débit à ralentir | | 413 | Fichier trop volumineux (5 Mo pour un CV, 10 Mo pour un besoin) | Ne pas réessayer tel quel | | 422 | La mission existe mais n'accepte pas encore de candidat | Déposer vers le vivier, et le signaler à un humain | | 429 | Trop d'appels sur une courte période | Attendre retryAfterSeconds | | 500 / status: 0 | Panne côté serveur, ou réseau injoignable | Réessayer une ou deux fois après une pause, puis signaler |

Le champ hint de chaque erreur reprend la colonne « Que faire » — l'agent n'a pas besoin de cette table pour bien réagir.

Un 403 sur check_import alors que les dépôts fonctionnent signale presque toujours une clé qui n'a que les capacités d'écriture : il lui manque candidate:read et mission:read.

check_import ne renvoie que des lots créés par la même clé. Un lot « introuvable » sur un identifiant que la clé n'a jamais reçu en retour d'un dépôt n'est pas un dysfonctionnement : ce lot appartient à quelqu'un d'autre.

Sécurité

En mode programme local, le serveur ne s'expose pas sur le réseau : votre agent le lance comme un processus enfant et lui parle par l'entrée et la sortie standard. Le seul appel réseau part de votre machine vers votre espace Nexhunter, en HTTPS.

En mode URL hébergée, la clé voyage uniquement dans l'en-tête Authorization, en HTTPS, et n'est jamais stockée côté serveur : chaque requête est authentifiée par l'API Nexhunter elle-même, avec les capacités, quotas et l'isolation par organisation déjà en place. Les fichiers fournis par fileUrl ne sont téléchargés que depuis des adresses https publiques.

Dans les deux cas, la clé n'agit que dans votre organisation, et uniquement dans la limite des capacités qui lui ont été accordées. Elle n'hérite pas des droits de la personne qui l'a créée. Elle est révocable à tout moment depuis Nexhunter, avec effet immédiat.

Gardez le secret hors de votre dépôt de code : passez-le par une variable d'environnement ou par le gestionnaire de secrets de votre plateforme.

Support

Pour un problème de clé, de quota ou de capacités, adressez-vous à votre contact Nexhunter.

© Nexhunter — licence commerciale. Ce paquet est destiné aux clients Nexhunter disposant d'un espace actif.