Développeurs et agents IA

Peetchr est nativement compatible avec les agents. Ses workflows de recrutement sont exposés aux agents IA via un serveur Model Context Protocol (MCP), protégé par OAuth 2.1. Cette page décrit comment un agent découvre Peetchr, s'authentifie et l'utilise.

Peetchr is a Talent Intelligence platform that plugs into an existing ATS and uses AI to evaluate candidates on hard skills, soft skills, culture fit, and team fit - no candidate test required - so recruiters get an explainable, ranked shortlist for every role across their new applicants, their existing ATS talent pool, and their employees.

Ce que les agents peuvent faire

Evaluate candidates against a role - Score and rank the candidates on a configured job across hard skills, soft skills, culture fit, and team fit, and return an explainable shortlist with per-dimension scores and fit reasons.
Reactivate the ATS talent pool - Search an organization indexed ATS pool for a newly opened role and surface previously-applied candidates who match, then run them through the same in-depth evaluation as fresh applicants.
Build and save job scorecards - Turn a job description into a weighted, adjustable scorecard (criteria, skills, thresholds), review the AI-generated draft, and publish it so candidates are scored against objective criteria.
Create and decide on candidates - Create jobs and candidates from documents, add CV attachments, assign candidates to jobs, and accept or reject applications with feedback that syncs back to the ATS.
Inspect credits and usage - Read an organization credit balance, transaction ledger, and AI usage totals by task and model.

Se connecter via MCP

Le serveur MCP utilise le transport Streamable HTTP et requiert un jeton OAuth 2.1. Un recruteur humain autorise l'accès ; les scopes suivent le moindre privilège.

Découvrir les métadonnées de ressource protégée (RFC 9728) pour trouver le serveur d'autorisation et la ressource MCP.
Enregistrer dynamiquement un client OAuth (RFC 7591).
Faire passer le recruteur par le flux authorization-code avec PKCE ; il approuve l'écran de consentement.
Échanger le code contre un jeton d'accès au token endpoint.
Appeler les outils MCP avec le jeton ; chaque appel est limité à l'organisation du recruteur.

Endpoints

MCP server (Streamable HTTP): https://app.peetchr.com/api/mcp
Protected-resource metadata (RFC 9728): https://app.peetchr.com/.well-known/oauth-protected-resource/api/mcp
Authorization server (RFC 8414): https://app.peetchr.com/.well-known/oauth-authorization-server
Register a client (RFC 7591): https://app.peetchr.com/api/auth/mcp/register
Authorize: https://app.peetchr.com/api/auth/mcp/authorize
Token: https://app.peetchr.com/api/auth/mcp/token

Démarrage rapide

Les identifiants sont en libre-service : un client s'enregistre lui-même et un recruteur approuve l'écran de consentement - aucun appel commercial n'est requis pour commencer.

Découvrir les exigences d'authentification (un appel non authentifié renvoie 401 avec l'URL des métadonnées)

curl -i https://app.peetchr.com/api/mcp
# HTTP/1.1 401 Unauthorized
# WWW-Authenticate: Bearer resource_metadata="https://app.peetchr.com/.well-known/oauth-protected-resource/api/mcp"

Enregistrer un client (RFC 7591) ; la réponse contient un client_id et un client_secret

curl -X POST https://app.peetchr.com/api/auth/mcp/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"my-agent","redirect_uris":["https://my-agent.example/callback"]}'

Faire passer le recruteur par le flux authorization-code + PKCE ; après approbation de l'écran de consentement, échanger le code renvoyé contre un jeton d'accès (en authentifiant le client)

curl -X POST https://app.peetchr.com/api/auth/mcp/token \
  -u '<CLIENT_ID>:<CLIENT_SECRET>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=<CODE>&code_verifier=<VERIFIER>&redirect_uri=<REDIRECT_URI>'

Lister et appeler les outils (JSON-RPC 2.0)

curl -X POST https://app.peetchr.com/api/mcp \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Scopes OAuth

openid - Authenticate the recruiter granting access (OpenID Connect).
profile - Read the granting recruiter profile.
email - Read the granting recruiter email.
offline_access - Obtain a refresh token for long-running sessions.
peetchr:recruiter - Read-only recruiter access: jobs, candidates, scorecards, credits.
peetchr:recruiter:write - Write recruiter access: create jobs/candidates, generate and save scorecards, accept/reject candidates.
peetchr:admin:recruiter - Peetchr-admin cross-organization recruiter actions (e.g. invite recruiters).
peetchr:admin:sql - Peetchr-admin read-only SQL access. Highly privileged; rarely granted.

Outils

Le serveur MCP publie le catalogue complet et typé via tools/list. Outils clés :

Lecture

listConfiguredJobs - List configured, active Peetchr jobs with candidate and score aggregates that mirror the /jobs page.
listJobCandidates - List candidates for one configured job, with score sorting and rediscovery / shortlist / rejected filters.
searchCandidates - Search organization-scoped candidates by candidateId, applicationId, jobId, or rediscovery flag; sortable by score.
searchCandidateApplications - Search applications and inspect stage, ATS/comment sync, rediscovery, verification, and score status.
presentCandidate - Return the recruiter-facing overview for one application: why-this-candidate summary, strengths, focus points, culture fit, scoring insights, and documents.
getCandidateData - Get full candidate debug data: profile, applications, reasoning-rich score history, attachments, questions, personality, and completion status.
getScorecardConfig - Get the saved scorecard (job configuration) for one job: criteria, weights, skills, thresholds, and flags.
getCreditBalance - Get the organization remaining credit balance and current-period usage.
editScorecardDraft - Merge and validate a scorecard configuration draft locally (no reads or writes) before saving. Available with the read scope.

Écriture (les changements de données demandent confirmation)

generateScorecard - Trigger AI scorecard generation for one job. Asynchronous; poll getGeneratedScorecard for the result. Requires peetchr:recruiter:write.
saveScorecard - Publish a job scorecard configuration. May create a new version and trigger rescoring; requires explicit user confirmation and peetchr:recruiter:write.
createJob - Create a job from structured data or an uploaded PDF/DOCX; both paths are LLM-structured identically. Requires peetchr:recruiter:write.
createCandidate - Create a candidate with one or more CV files and assign it to a job; runs the normal parsing and scoring pipeline. Requires peetchr:recruiter:write.
parseDocument - Parse an uploaded PDF/DOCX into structured text for downstream job or candidate creation.
acceptCandidate - Accept (shortlist) one application, with optional feedback. Applied immediately in Peetchr; ATS push depends on sync settings. Requires confirmation and peetchr:recruiter:write.
rejectCandidate - Reject one application, with optional feedback. Applied immediately in Peetchr; ATS push depends on sync settings. Requires confirmation and peetchr:recruiter:write.

Admin (administrateurs Peetchr uniquement)

findOrganizations - Match a Peetchr organization by exact id or name so a Peetchr admin can target it. Peetchr admins only.
inviteRecruiter - Invite a recruiter into an organization; sends an email on every call. Requires confirmation. Peetchr admins only.

Ressources exploitables par machine

Agent guide (agents.md) - When to use Peetchr and how an agent connects, in prose.
Agent auth walkthrough (auth.md) - Step-by-step OAuth credential flow for agents.
OpenAPI specification - Machine-readable description of the OAuth + MCP entry points.
MCP server card - Preview of the MCP server, transport, and tools.
Agent Skills index - Machine-readable list of Peetchr agent capabilities.
Agent card - Agent capability descriptor naming the MCP interface.
MCP server endpoint - Streamable HTTP MCP transport (OAuth-protected).
Developer & agent docs - Human-readable overview of the agent surface.

Limites

Peetchr is business software: every tool is OAuth-scoped to the recruiter organization that grants access and to its active ATS-linked accounts. There is no anonymous access.
Peetchr evaluates and ranks candidates and syncs decisions to the ATS; it is not a job board and does not itself send offers or contracts.
Write actions that change data or contact people (save scorecard, accept/reject a candidate, invite a recruiter) require explicit user confirmation.
It is not a general web-search or chat assistant: tools act only on the granting organization jobs, candidates, and talent pool.
Candidate scoring is asynchronous - creating or reconfiguring work enqueues evaluation rather than returning a score synchronously.