Recruitee MCP

Gestiona tu pipeline de Recruitee / Tellent desde dentro de Claude. Consulta un puesto, lee un candidato y todo lo que ya se ha registrado sobre él, añade a alguien que hayas encontrado y escribe tu evaluación de la entrevista, sin salir de la conversación.

Se ejecuta en tu propia máquina con tu propio token de API de Recruitee, así que todo lo que escribe se archiva en tu nombre, exactamente como si lo hubieras hecho tú mismo.

Lo que puede hacer

Catorce herramientas. Nueve de lectura, cinco de escritura, y cada escritura te muestra exactamente lo que va a hacer antes de hacerlo.

Lectura

Las respuestas a la solicitud merecen una mención: las expectativas salariales y similares se devuelven por puesto, porque alguien que se postuló a tres trabajos respondió a la pregunta tres veces, y una lista plana no puede distinguir esas respuestas.

Escritura

Cómo se comportan las escrituras

Usan nombres, no ids. "Dana Whitfield", "Regional Sales Manager". Si un nombre coincide con dos personas, se detiene y las lista en lugar de elegir una — archivar un veredicto sobre la persona equivocada es el fallo que realmente importa aquí.

Todas se previsualizan primero. La primera llamada devuelve exactamente lo que se escribiría y no escribe nada. Solo después de que apruebes se registra algo. Para un candidato nuevo, la previsualización también ejecuta una comprobación de duplicados y te dice qué detalles faltan, para que lo sepas antes de que exista el registro, no después.

Las evaluaciones se archivan contra la etapa real actual del candidato, que es lo que significa una evaluación. Puedes anularla deliberadamente, pero nunca tienes que averiguarla.

Tus párrafos sobreviven. El campo de notas de Recruitee acepta texto plano, pero su interfaz renderiza ese texto como HTML, así que una nota escrita en párrafos llegaría de otro modo como un bloque continuo. Los saltos de línea se convierten en el camino, y el texto se escapa primero para que un < suelto en tu escritura no pueda ser tragado o renderizado.

Las valoraciones se comprueban, no se redondean. Los valores válidos dependen de tu escala configurada — una escala de pulgares de 4 puntos no tiene "neutral", una de 5 sí. Un valor que la escala no tiene se rechaza en lugar de convertirse silenciosamente en un vecino.

Related MCP server: Recruitee MCP Server

Búsqueda en tu propia base de datos

rt_source_candidates ejecuta la misma búsqueda que la pantalla de Candidatos, que es algo diferente de rt_search_candidates: esa coincide con nombres, esta coincide con todo, incluido el texto del CV, con operadores booleanos.

query: "renewals AND churn"
query: "(SaaS OR B2B) AND \"net revenue retention\" NOT \"vice president\""

Eso importa porque los títulos de trabajo son inconsistentes entre empresas, y lo que alguien realmente hizo está escrito en su CV. Buscar la evidencia es mejor que buscar el título.

Los filtros se combinan: offer, excludeOffer, jobStatus, stage, status, tags, sources. excludeOffer es el que lo convierte en una herramienta de búsqueda en lugar de un cuadro de búsqueda — mantiene a las personas que ya están en un puesto fuera de los resultados cuando lo estás completando.

Cada resultado lleva por qué coincidió — las frases reales, con el HTML eliminado — y cada puesto en el que la persona ya está, con la etapa y, donde fue rechazada, la razón. Esa última parte no es decoración: la mayoría de un ATS establecido fue rechazado una vez. "Ubicación incorrecta" hace dos años puede no aplicar hoy; "falló la evaluación" todavía sí. Nadie debería presentarse como un hallazgo nuevo sin eso.

Por qué la construcción de filtros parece paranoica

/search/new/candidates ignora silenciosamente cualquier cosa que no reconoce y devuelve un resultado sin filtrar en lugar de un error. Cuatro formas de obtener una respuesta plausible y gravemente incorrecta, todas confirmadas contra una cuenta en vivo:

Ese último es el más desagradable: un puesto más un estado de trabajo enviados como dos objetos devuelve a todos con ese estado de trabajo, y nada en ningún lugar dice que el filtro de puesto se haya eliminado. Así que cada restricción sobre una entidad se fusiona en un solo objeto, y ninguna clave proporcionada por el llamador llega nunca a la API — los nombres se mapean a un vocabulario verificado contra la API en vivo, y cualquier cosa fuera de él lanza una excepción.

Un valor incorrecto es seguro en contraste: devuelve cero, que es obviamente incorrecto para quien lo lee. Un resultado de cero también viene con tus nombres de etapa reales adjuntos, así que una etapa mal escrita se distingue de una vacía.

node sourcing-test.js comprueba todo eso, incluido que el cliente rechaza cada uno de los cuatro errores anteriores.

Configuración

Cinco minutos, una vez. Necesitas Node 18 o superior (node -v para comprobar) y Claude Code o la aplicación de escritorio de Claude.

1. Instalar

npm install

2. Crear tu propio token de API

En Recruitee: Settings → Apps and plugins → API tokens, permanece en la pestaña Personal API tokens y haz clic en + Add token. Te pide tu contraseña y luego muestra el valor una sola vez.

Mientras estás en esa pantalla, anota tu empresa desde el panel Current company details en la parte superior. Funciona tanto el ID numérico como el subdominio.

Este tiene que ser tu token, no uno compartido. Un token de Recruitee actúa como la persona que lo creó, así que una evaluación escrita con tu token aparece como tuya — que es el punto. Nunca lo pegues en un chat, un correo electrónico o un ticket.

3. Almacenarlo

npm run set-token -- <paste-your-token-here> <your-company>

Rotar un token más tarde es solo npm run set-token -- <nuevo-token> — la empresa se recuerda.

Se escribe en session/token.json, legible solo por ti, y está en gitignore. RECRUITEE_API_TOKEN en el entorno anula el archivo si prefieres mantenerlo en un gestor de contraseñas.

4. Demostrar que funciona

npm run check

Quieres authenticated: true y algunos de tus puestos.

5. Conectarlo a Claude

Ejecuta esto desde dentro de esta carpeta y luego reinicia Claude:

claude mcp add recruitee -- node "$PWD/server.js"

¿Usas la aplicación de escritorio de Claude? Abre Settings → Developer → Edit Config y añade esto, con tu ruta absoluta real (pwd la imprime):

{
  "mcpServers": {
    "recruitee": {
      "command": "node",
      "args": ["/absolute/path/to/recruitee-mcp/server.js"]
    }
  }
}

Luego pregunta a Claude: "lista los puestos abiertos en Recruitee".

Cómo se ve en uso

Tú: ¿Quién está en el pipeline para Regional Sales Manager?

Tú: Saca a Dana Whitfield — ¿qué puso para el salario y qué evaluaciones ya tiene?

Tú: Escribe una evaluación para ella en ese puesto. Un sí: fuerte en renovaciones y expansión, dirigió un equipo de nueve, sin experiencia en PLG.

Claude te muestra la valoración, la nota, el puesto y la etapa, y no escribe nada.

Tú: Sí, envíalo.

Lo que deliberadamente no puede hacer

Un token de API de Recruitee lleva exactamente los permisos de la persona que lo generó — la documentación es explícita de que puede "realizar las mismas acciones que en la aplicación web o móvil en nombre de ese usuario". No hay token de solo lectura que emitir.

Así que la restricción vive en este código en su lugar. Descalificar, recalificar, eliminar, ocultar y anonimizar son todos endpoints reales y documentados que este servidor no implementa. No ocultos detrás de una bandera, no comentados — ausentes, para que ninguna instrucción, prompt o error pueda alcanzarlos. Rechazar a un candidato sigue siendo una decisión que tomas en la interfaz.

Los movimientos de etapa son lo único que está permitido. rt_set_stage avanza a un candidato a lo largo del pipeline de una oferta, porque eso es contabilidad en lugar de un juicio, y un pipeline que no puedes avanzar desde aquí se desvía de dondequiera que lo rastrees. La línea se traza en la descalificación y se aplica, no solo se documenta: el movimiento rechaza una colocación que ya ha sido descalificada, ya que cambiar su etapa recalificaría a la persona — revirtiendo el rechazo de alguien como efecto secundario de una llamada contable.

npm run smoke afirma estas propiedades en cada ejecución: que no se expone ninguna herramienta destructiva, que el movedor de etapas rechaza una colocación descalificada y está limitado a una oferta, y que cada escritura anuncia su puerta de confirmación. Esa última comprobación deriva las escrituras de los esquemas de las herramientas en lugar de una lista de patrones de nombres — la versión anterior dejó de cubrir silenciosamente nuevas herramientas y dejó pasar rt_set_stage sin probarlo en absoluto.

Cosas que vale la pena saber

Los nuevos candidatos llegan a "Sourced". El endpoint de creación de Recruitee siempre coloca a las personas en "Applied", lo que clasificaría a todos los que hayas buscado entre los solicitantes genuinos, por lo que se mueven inmediatamente después de su creación y se te informa si no se logró. Pasa stage para anularlo: "Applied" para alguien que realmente solicitó, o cualquier etapa posterior para alguien que ya está en proceso. Para moverlos después, usa rt_set_stage.

Establecer un CV reemplaza al que ya existe. set_as_cv de Recruitee no añade un CV; intercambia la ranura y degrada el archivo anterior a un adjunto simple. Por lo tanto, rt_attach_file se niega a establecer un CV en un candidato que ya tiene uno a menos que pases replaceCv — un CV registrado es decisión de alguien, y la única huella de sobrescribirlo es una fila extra en la lista de adjuntos.

Las evaluaciones se registran bajo tu nombre. Aparecen como "Tú evaluaste", indistinguibles de una hecha a mano. Nunca escribas una para una conversación que no tuviste o no has leído, y si el juicio provino de un colega, menciónalo en la nota.

La atribución no es fiable al volver. Cualquier cosa escrita a través de cualquier token de API se atribuye al propietario de ese token, por lo que el evaluador en una evaluación sincronizada por alguien puede ser quien la sincronizó, no quien realizó la entrevista. La nota normalmente nombra al real.

Las tarjetas de puntuación de cuestionarios no son compatibles. Solo la tarjeta de calificación simple. La API documenta las respuestas por pregunta en cada respuesta, pero nunca en un cuerpo de solicitud, por lo que la forma de escritura tendría que observarse de una presentación real primero. Puede que tampoco importe para tu cuenta: si /results/scorecards vuelve vacío para personas que han pasado por etapas de entrevista, entonces se están usando tarjetas de calificación simples y no falta nada. Vale la pena verificarlo antes de que alguien invierta en la ruta del cuestionario.

Dónde funciona esto

Este es un servidor MCP local stdio — Claude lo lanza como un proceso en tu máquina, y tu token nunca sale de ella.

• Claude Code (terminal, aplicación de escritorio, extensiones de IDE) ✅

• Aplicación de escritorio de Claude ✅

• claude.ai en un navegador ❌ — eso se conecta solo a servidores MCP remotos accesibles mediante HTTPS, lo que implicaría alojar esto y almacenar los tokens de Recruitee de todos en ese host.

Configuración

Solución de problemas

Desarrollo

npm run smoke     # self-check: tool list, no destructive tools, confirm gates, one live read
npm run sourcing  # 20 checks on the search filters, including the four silent-failure modes
npm run check     # prove the token
npm start         # run the server directly (it speaks JSON-RPC on stdin/stdout)

Dos notas de implementación, ambas encontradas mediante prueba y error en lugar de los documentos:

• La subida de archivos no está documentada. La referencia describe un cuerpo JSON que lleva un path del lado del servidor que nunca explica cómo obtener. Una simple solicitud POST multipart funciona, con la parte del archivo nombrada attachment[file] — un file simple devuelve 500, y pasar el id del candidato como parámetro de consulta crea un adjunto sin vincular a nadie. Promover un archivo a la ranura de CV lo reemplaza con un nuevo id y un nombre de archivo generado, por lo que las subidas se verifican contra la URL del CV del candidato en lugar del id que se acaba de subir.

• /search/new/candidates ignora su propio parámetro de consulta y devuelve todos los registros de la empresa, por lo que la búsqueda por nombre pasa por /candidates?query= en su lugar. Las etapas del pipeline provienen de /offers/{id}/placements, agrupadas por etapa, no de /offers/{id}/pipeline_templates, que lista plantillas disponibles para un rol sin sus etapas.