# Peetchr for AI agents 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. ## When to use Peetchr - A recruiter or hiring workflow needs candidates on a role scored and ranked with explainable reasoning, not keyword matching. - You want to know whether a good fit for a new role already exists in a company ATS talent pool before sourcing externally. - You need to turn a job description into a structured, weighted scorecard and evaluate applicants against it. - You need to create jobs or candidates in Peetchr from CVs / job files, or accept/reject candidates and have the decision sync to the connected ATS. - You need per-candidate evidence: hard-skill and soft-skill scores, culture and team fit, strengths, and points to verify. ## How an agent connects Peetchr exposes a Model Context Protocol (MCP) server over the Streamable HTTP transport at `https://app.peetchr.com/api/mcp`. All tools require an OAuth 2.1 access token; there is no anonymous access. 1. **Discover.** Fetch the protected-resource metadata (RFC 9728): `https://app.peetchr.com/.well-known/oauth-protected-resource/api/mcp`. It names the authorization server (`https://app.peetchr.com`) and the MCP resource. An unauthenticated call to the MCP endpoint also returns `401` with a `WWW-Authenticate: Bearer resource_metadata="..."` header. 2. **Register.** Dynamically register a client (RFC 7591) at `https://app.peetchr.com/api/auth/mcp/register`, supplying your `redirect_uris`. 3. **Authorize.** Send the recruiter through the authorization-code flow with PKCE (`S256`) at `https://app.peetchr.com/api/auth/mcp/authorize`. A human recruiter approves the consent screen and the requested scopes. 4. **Token.** Exchange the code at `https://app.peetchr.com/api/auth/mcp/token` for an access token (and, with `offline_access`, a refresh token). 5. **Call tools.** Send `Authorization: Bearer ` to `https://app.peetchr.com/api/mcp` and call the tools below. Every tool is scoped to the granting recruiter organization and its active ATS-linked accounts. See the full credential walkthrough at https://peetchr.com/auth.md. ## Quickstart Credentials are self-serve: a client registers itself (RFC 7591) and a human recruiter approves the consent screen. No sales call is required to start. ### 1. Discover the auth requirements An unauthenticated call returns `401` with a pointer to the protected-resource metadata: ```bash 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" ``` ### 2. Register a client (RFC 7591) Dynamic registration returns a `client_id` and `client_secret`: ```bash 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"]}' ``` ### 3. Authorize (code + PKCE), then exchange for a token Send the recruiter to `https://app.peetchr.com/api/auth/mcp/authorize` with `response_type=code`, your `client_id`, `redirect_uri`, `scope`, and a PKCE `code_challenge` (`S256`). After they approve the consent screen, exchange the returned code - authenticating the client, since the token endpoint accepts `client_secret_basic`/`client_secret_post`: ```bash curl -X POST https://app.peetchr.com/api/auth/mcp/token \ -u ':' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=authorization_code&code=&code_verifier=&redirect_uri=' ``` ### 4. List and call tools (JSON-RPC 2.0) ```bash curl -X POST https://app.peetchr.com/api/mcp \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` Call a specific tool with `tools/call`: ```json {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"listConfiguredJobs","arguments":{}}} ``` Read tools need the `peetchr:recruiter` scope; write tools need `peetchr:recruiter:write`. Full request/response shapes are in the OpenAPI spec at https://peetchr.com/openapi.json. ## Capabilities - **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. ## Tools The live MCP server publishes the full, schema-typed catalog via `tools/list`. Key tools: ### Read - `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. ### Write (requires explicit user confirmation for data changes) - `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 - `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. ## OAuth scopes - `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. ## Constraints - 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. ## FAQ ### What is Peetchr? 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. ### Does Peetchr have an API for AI agents? Yes. Peetchr exposes a Model Context Protocol (MCP) server at https://app.peetchr.com/api/mcp using the Streamable HTTP transport. Agents authenticate with OAuth 2.1 (authorization code + PKCE, with dynamic client registration) and then call typed tools to list jobs, evaluate candidates, build scorecards, and accept or reject applications. See https://peetchr.com/auth.md and https://peetchr.com/agents.md. ### How does an AI agent authenticate with Peetchr? Peetchr runs an OAuth 2.1 authorization server on the recruiter app (https://app.peetchr.com). Agents discover it via https://app.peetchr.com/.well-known/oauth-protected-resource/api/mcp, dynamically register a client at https://app.peetchr.com/api/auth/mcp/register, and obtain an access token through the authorization-code flow with PKCE. A human recruiter approves the consent screen; scopes are least-privilege (read vs write). ### Which ATS does Peetchr integrate with? Peetchr connects to 90+ applicant tracking systems in one click (via the Kombo integration layer), including Greenhouse, Workday, Lever, SmartRecruiters, and Teamtailor. Jobs and candidates sync continuously and decisions can sync back as tags and stage movements. ### How does Peetchr score candidates? Peetchr converts each job description into a weighted scorecard (Hard Skills, Soft Skills, Culture Fit, Team Fit) and reasons over the candidate concrete achievements, career trajectory, and company context - drawing on 40,000+ skills and standards like ROME, ESCO, ISCO, Big Five, Birkman, and DISC - rather than matching CV keywords. Every recommendation comes with natural-language reasoning. ### Is Peetchr GDPR and EU AI Act compliant? Yes. Peetchr is built for sensitive HR data with processing aligned to GDPR and the EU AI Act, data hosting in your chosen region, TLS 1.2+ in transit and AES-256 at rest, contractual documentation (DPA, DPIA, FRIA), and explainable AI scores. Compliance details are in the Peetchr Trust Center. ## Resources - [Agent guide (agents.md)](https://peetchr.com/agents.md) - When to use Peetchr and how an agent connects, in prose. - [Agent auth walkthrough (auth.md)](https://peetchr.com/auth.md) - Step-by-step OAuth credential flow for agents. - [OpenAPI specification](https://peetchr.com/openapi.json) - Machine-readable description of the OAuth + MCP entry points. - [MCP server card](https://peetchr.com/.well-known/mcp/server-card.json) - Preview of the MCP server, transport, and tools. - [Agent Skills index](https://peetchr.com/.well-known/agent-skills/index.json) - Machine-readable list of Peetchr agent capabilities. - [Agent card](https://peetchr.com/.well-known/agent-card.json) - Agent capability descriptor naming the MCP interface. - [MCP server endpoint](https://app.peetchr.com/api/mcp) - Streamable HTTP MCP transport (OAuth-protected). - [Developer & agent docs](https://peetchr.com/en/developers) - Human-readable overview of the agent surface. ## Contact - Email: hello@peetchr.ai - Company: Peetchr SAS (RCS Paris B 980 220 164)