HireLayer MCP server
This server enables AI agents to parse resumes, extract job criteria, evaluate and rank candidates, and normalize skills through HireLayer.
Parse resumes/CVs from a local path or public URL into structured JSON (contact details, experience, education, languages, skills, full text), up to 4.5 MB, for 1 credit.
Extract weighted, mandatory-flagged matching criteria with rationales from any job description, for 1 credit.
Score one candidate against a job from resume text, returning a 0–1 score and per-criterion evaluation, optionally using extracted criteria.
Rank up to 10 candidates against the same job description, at 1 credit per call.
Resolve free-text skills (single skill, compound string, or full skills section) to HireLayer taxonomy IDs and labels in French or English.
Optionally echo a caller-supplied application_id and, on supported plans, avoid storing parsed file data.
Note: the schema exposes older 1.x tool names (match_candidate, rank_candidates, resolve_skills); the README documents newer replacements and additional search tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@HireLayer MCP server Parse ~/Downloads/jane-doe.pdf and summarize her experience."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
HireLayer MCP Server
Resume parsing, resume scoring and talent pool search for AI agents.
The official Model Context Protocol server for HireLayer. Parse resumes and CVs, turn job descriptions into criteria, score and rank resumes against a job, and search the candidates and jobs you already have, from Claude, ChatGPT, Cursor, VS Code, Codex or any MCP client.
Server URL: https://hirelayer.co/mcp · sign in with your HireLayer account, no API key to copy.
"Screen these 3 resumes against the Senior React job and tell me who to interview."
Your assistant parses each CV, scores every candidate against the job criterion by criterion and explains the shortlist.
Contents
Related MCP server: matchcv-mcp
What you can do
Parse resumes and CVs (Resume Parser). Turn PDF, Word, image and other files into structured JSON: contact details, work experience, education, languages, skills and the full text. Scanned resumes go through OCR, and the resume language is detected.
Turn a job description into criteria (Job Criteria Extractor). Get the typed, weighted criteria the posting states, each marked required, preferred or bonus, in English, French, German, Spanish or Portuguese. Free.
Score and rank resumes (Resume Scorer). Score up to 50 resumes against a job in one call, from 0 to 1, with a verdict, a summary and the evidence for each criterion, best first. Ask for a precise ranking to re-rank the 10 best with a reason each.
Search your talent pool (Talent Pool Search). Find the resumes already in your HireLayer database closest to a job, around a city if you like.
Recommend jobs (Job Recommendations). Find your open jobs closest to a candidate.
Normalize skills (Skills Normalizer). Map free-text skills to a skills taxonomy with stable IDs, named in French or English.
Use it to screen applicants in a chat, build a recruiting agent, enrich an ATS, or prototype HR tech features without writing integration code.
Quick start
Add the server URL
https://hirelayer.co/mcpin your AI app, or click a one-click install button above.Sign in to HireLayer when your app asks, and allow access. No account yet? Sign up for free: 50 credits a month, no card required.
Ask your assistant. For example: attach a resume and ask "Summarize this candidate."
To try it without your own data, use the sample job and resumes in examples/. The repository ships a .mcp.json: clone it, export HIRELAYER_API_KEY, open the folder in Claude Code and it offers to enable the local server.
Install in your MCP client
Hosted server (recommended)
Connect to https://hirelayer.co/mcp and sign in to HireLayer. Nothing to install, nothing to keep up to date.
Client | How to connect |
Claude (web, desktop, mobile) | Settings → Connectors → Add custom connector, paste the URL, then Connect |
ChatGPT | Settings → Apps → turn on developer mode, create an app with the URL and OAuth authentication |
Claude Code |
|
Cursor | Click Install in Cursor above, or add |
VS Code | Click Install in VS Code above, or add |
Codex CLI |
|
Clients that cannot sign in with OAuth can send a HireLayer API key instead: Authorization: Bearer your-api-key.
The hosted parse_resume takes a file attached in ChatGPT, a public HTTPS URL, a small file in base64 or the resume text. To parse files from your disk, run the server locally.
Local server (npx)
Runs on your machine with an API key: sign up, then copy your key from Dashboard → API keys and replace your-api-key below.
claude mcp add hirelayer --env HIRELAYER_API_KEY=your-api-key -- npx -y hirelayer-mcpOpen Settings → Developer → Edit Config and add the server to claude_desktop_config.json:
{
"mcpServers": {
"hirelayer": {
"command": "npx",
"args": ["-y", "hirelayer-mcp"],
"env": { "HIRELAYER_API_KEY": "your-api-key" }
}
}
}Restart Claude Desktop.
Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"hirelayer": {
"command": "npx",
"args": ["-y", "hirelayer-mcp"],
"env": { "HIRELAYER_API_KEY": "your-api-key" }
}
}
}Add this to .vscode/mcp.json. VS Code asks for your API key and stores it securely:
{
"inputs": [
{ "type": "promptString", "id": "hirelayer_api_key", "description": "HireLayer API key", "password": true }
],
"servers": {
"hirelayer": {
"type": "stdio",
"command": "npx",
"args": ["-y", "hirelayer-mcp"],
"env": { "HIRELAYER_API_KEY": "${input:hirelayer_api_key}" }
}
}
}Add this to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"hirelayer": {
"command": "npx",
"args": ["-y", "hirelayer-mcp"],
"env": { "HIRELAYER_API_KEY": "your-api-key" }
}
}
}codex mcp add hirelayer --env HIRELAYER_API_KEY=your-api-key -- npx -y hirelayer-mcpgemini mcp add -e HIRELAYER_API_KEY=your-api-key hirelayer npx -y hirelayer-mcpAny client that runs stdio MCP servers works with this command and environment variable:
Command:
npx -y hirelayer-mcpEnvironment:
HIRELAYER_API_KEY=your-api-key
Cline users can also ask Cline to install the server: llms-install.md has the steps.
docker build -t hirelayer-mcp .
docker run -i --rm -e HIRELAYER_API_KEY=your-api-key hirelayer-mcpIn Docker, parse_resume only reads files that you mount into the container. Otherwise, pass file_url or resume_text.
Tools
Tool | Product | What it does | Typical input |
| Resume Parser | Parses a resume or CV into structured JSON: contact details, experience, education, languages, skills and the full text, stored under an | A local |
| Job Criteria Extractor | Turns a job description into the typed criteria it states, each with a requirement (required, preferred or bonus) and a weight from 0 to 3, and stores the job under a | Job description text, at least 30 characters |
| Resume Scorer | Scores 1 to 50 resumes against one job, best first: a score from 0 to 1, a verdict, a summary, the required criteria missing and the evidence for each criterion. | The job as |
| Talent Pool Search | Finds the stored resumes closest to a job, with optional city, radius and date filters. Proximity only: score the ones worth it with | A |
| Job Recommendations | Finds the stored open jobs closest to a resume. Proximity only | An |
| Skills Normalizer | Maps free-text skills to taxonomy skills, with their families and domains, named in French or English | Free text, from one skill to a whole skills section |
HireLayer keeps the resumes, jobs and scores in your HireLayer account, as the REST API does, so a resume or a job-resume pair already processed costs nothing the second time and the two searches have something to search. normalize_skills stores nothing. No tool deletes anything or changes your other systems.
Several client companies? Every tool except normalize_skills takes an optional workspace (for example acme-corp), sent as the HireLayer-Workspace header: each client's jobs, resumes and scores stay apart. A new id creates a new workspace; without one, calls use your default workspace.
Upgrading from 1.x: match_candidate and rank_candidates became score_resumes, and resolve_skills became normalize_skills. See the changelog.
The server also ships prompts that clients show as ready-made commands:
Prompt | What it does |
| Parses the resume files, scores every resume against the job in one call with a precise ranking, and writes a shortlist |
| Parses one resume and writes a recruiter summary |
| Normalizes a skills section and groups it by domain |
How screening works
flowchart LR
J[Job description] --> S[score_resumes]
R[Resume files] --> P[parse_resume]
P -- application_id --> S
T[Resume texts] --> S
J -. review criteria first .-> C[extract_job_criteria]
C -. job_id .-> S
D[(Your talent pool)] --> Q[search_resumes]
Q -- application_ids --> S
S --> L[Shortlist with evidence]Trimmed to one resume and one criterion:
{
"job": {
"job_id": "job_8f14e45fceea167a5a36dedd4bea2543",
"title": "Senior React Developer",
"language": "en"
},
"precise_ranking": true,
"scores": [
{
"rank": 1,
"application_id": "text_c4ca4238a0b923820dcc509a6f75849b",
"reference": "alex-morgan",
"evaluation_status": "completed",
"score": 0.91,
"verdict": "highly_relevant",
"summary": "Strong fit: 8 years of React and TypeScript, team lead, automated testing with Jest and Playwright. Health tech experience to confirm.",
"ranking_reason": "The only candidate who has led a React and TypeScript team in production.",
"required_missing": [],
"to_verify": [],
"criteria": [
{
"criterion_id": "crit_2",
"label": "React experience",
"requirement": "required",
"weight": 3,
"status": "met",
"score": 1,
"evidence": "Lead Front-End Engineer, Medisoft: 'Lead a team of 4 developers on a React 18 + TypeScript appointment platform'",
"explanation": "Over 3 years of React, the last ones leading a team on a production platform."
}
]
}
],
"credits_used": 3
}Criteria, summaries and explanations are written in the job's language (English, French, German, Spanish or Portuguese; English for any other) unless you pass language; evidence quotes the resume in its own language.
Example prompts
Recruiters and hiring managers
"Parse
~/Downloads/jane-doe.pdfand summarize her experience in five bullet points.""Here is our job description for a Senior Data Engineer. Extract the criteria, then tell me which ones are required."
"Score the resumes in
~/candidates/against this job and give me a shortlist table with scores and main gaps.""Rank these 8 candidates for the Account Executive role with a precise ranking and explain why the top 3 stand out."
"Does this candidate meet every required criterion? If not, which ones are missing?"
"Which candidates already in my HireLayer database fit this job? Keep those within 50 km of Lyon."
"Which of our open jobs suit this candidate?"
"For our client Acme Corp (workspace
acme-corp), score these resumes against their Product Manager job."
Developers and HR tech teams
"Parse this resume and map the result to our ATS candidate schema:
{ name, email, current_title, skills[] }.""Normalize this skills section: Pack Office (Word, Excel), React.js, anglais courant, gestion de projet."
"Write a TypeScript function that sends a resume to the HireLayer API, using the JSON this tool returned as the expected type."
Try it now with the sample files
"Screen the resumes in
examples/againstexamples/job-senior-react-developer.md."
Pricing and credits
Tool | Credits |
| 1 per resume, 0 for a file already stored |
| Free (a new text for a job already scored evaluates its scores again, 1 credit each) |
| 1 per resume evaluated, 0 for a job-resume pair already scored; 1 more per call with |
| 1 per search |
| 1 |
Failed calls and resumes that fail are not charged, and a call refused for lack of credits processes nothing.
Plan | Credits | Price |
Free | 50 a month | Free, no card required |
Paid plans | More credits and higher limits |
Data and privacy
The hosted server receives only what your assistant sends to HireLayer tools. Each app gets access only after you sign in and allow it, and you can disconnect it at any time.
The local server runs on your machine and calls the HireLayer API over HTTPS with your API key. It has no telemetry.
parse_resumereads only the file you name. HireLayer stores the resume in your account under itsapplication_id, keeps the original file and returns a link to it inresume.info_resume.url. On the Enterprise plan, setdo_not_store_data: truein a call so nothing of the parse is kept.The jobs, resumes and scores the tools process stay in your HireLayer account, in the workspace of the call, so you can score and search them again later.
See the privacy policy and the security policy.
Resumes contain personal data. Use the tools in line with your hiring process and the rules that apply to you, such as GDPR. Scores support human decisions; they don't replace them.
Configuration
Variable | Required | Default | Description |
| Yes | Your HireLayer API key | |
| No |
| API base URL, for testing |
Troubleshooting
Symptom | Fix |
| Add the |
| The key is wrong or revoked. Copy it again from Dashboard → API keys. |
| You have used your monthly credits. Wait for the reset or upgrade your plan. |
|
|
| You run a 1.x version, which calls retired endpoints. Update to the latest version with |
Parsing or scoring seems slow | Parsing usually takes about 30 seconds, and longer for scans that need OCR; scoring 50 resumes takes about a minute. The server sends progress updates so clients don't time out. |
| Install Node.js 20 or later from nodejs.org. |
The file is not found | Use an absolute path, for example |
To debug, run the server in the MCP Inspector:
HIRELAYER_API_KEY=your-api-key npx @modelcontextprotocol/inspector npx -y hirelayer-mcpFAQ
Is HireLayer an ATS? No. HireLayer provides the AI building blocks of recruiting software: resume parsing, scoring and ranking, talent pool search and skills. Use them on their own through MCP, or plug them into your ATS or HR tech product through the REST API.
Which language are the results in?
The text that HireLayer writes (criteria, summaries, explanations and ranking reasons) is in the job's language: English, French, German, Spanish or Portuguese, and English for a job written in another language. Choose it with language (en, fr, de, es or pt). Evidence quotes the resume in its own language. Skills normalization returns French or English labels.
Which resume languages are supported?
The parser detects the main language of each resume and returns it in resume.info_resume.language.
Can I use the REST API directly?
Yes. See the API reference, the OpenAPI spec and llms.txt for agents.
Do I need an API key? Not with the hosted server: you sign in to HireLayer and allow access, and the app's calls use your plan's credits. Each connected app appears as an "(MCP)" key in Dashboard → API keys; revoke it to disconnect the app. The local server uses an API key.
Development
git clone https://github.com/hirelayer/hirelayer-mcp.git
cd hirelayer-mcp
npm install
npm test
HIRELAYER_API_KEY=your-api-key npx @modelcontextprotocol/inspector node dist/index.jsSee CONTRIBUTING.md. Report bugs in GitHub issues and vulnerabilities as described in SECURITY.md.
Links
Website: hirelayer.co
API reference: hirelayer.co/api-docs
OpenAPI: hirelayer.co/openapi.json
Docs for agents: hirelayer.co/llms.txt
Contact: contact@hirelayer.co
License
Available Tools
6 toolsextract_job_criteriaJob Criteria ExtractorAInspect
Turn a job description (any language, at least 30 characters) into the typed criteria it states (usually 4 to 10, fewer for a short posting), in the posting's order, each with a criterion_id, a label, a type, a requirement (required, preferred or bonus), a weight from 0 to 3 and an optional threshold. They are written in the job's language (English, French, German, Spanish or Portuguese; English for any other) unless language says otherwise. The job is stored under job_id, so score_resumes can reuse it. Free, except a new text sent under the job_id of a job already scored: its scores are evaluated again, 1 credit each.
Inputs: job_text (required), title, job_id, language, +2 more.
normalize_skillsSkills NormalizerARead-onlyInspect
Map free-text skills (one skill, a compound string or a whole skills section) to skills of the HireLayer taxonomy, with their IDs, families and domains, named in French or English. Unmatched parts are listed in unresolved. Costs 1 HireLayer credit.
Inputs: text (required), language.
parse_resumeResume ParserAInspect
Parse a resume / CV (PDF, DOC, DOCX, ODT, PPT, PPTX, ODP, XLS, RTF, TXT, HTML, Markdown, JPG, PNG or BMP, under 4.5 MB) into structured JSON, in resume: contact details, work experience, education, languages, skills and the full resume text in resume.info_resume.text. Give exactly one input: file_path (a local file), file_url (a public URL) or resume_text. HireLayer keeps the resume in the user's resume database under application_id, unless do_not_store_data is set. Takes about 30 seconds. Costs 1 HireLayer credit, 0 for a file already stored.
Inputs: file_url, file_path, workspace, resume_text, +2 more.
score_resumesResume ScorerAInspect
Evaluate 1 to 50 resumes against a job, criterion by criterion, and return them best first: for each, a score between 0 and 1, a verdict (highly_relevant, relevant, marginally_relevant or not_relevant), a summary, the required criteria missing or to verify, and the evidence for each criterion. Give the job as job_text (its criteria are extracted on the way, or pass your own criteria) or as the job_id of a stored job. Give each resume as text or as the application_id of a stored resume; at least one resume of the call holds 30 characters or more. Summaries and explanations are written in the job's language. With precise_ranking, the 10 best are re-ranked against each other, each with a ranking_reason. The result is decision support for a human recruiter, not an automated hiring decision. Costs 1 HireLayer credit per resume evaluated, and 1 more with precise_ranking; a pair already scored costs 0.
Inputs: resumes (required), job_id, criteria, job_text, +3 more.
search_jobsJob RecommendationsAInspect
Find the user's stored open jobs closest to a resume, by proximity only: job_ids with their title and a similarity between 0 and 1, best first, and whether the resume is already scored for each. No evaluation: score the ones worth it with score_resumes. Give the resume as the application_id of a stored resume or as resume_text (the resume is then stored). Costs 1 HireLayer credit per search.
Inputs: limit, workspace, resume_text, application_id.
search_resumesTalent Pool SearchAInspect
Find the resumes of the user's resume database closest to a job, by proximity only: application_ids with a similarity between 0 and 1, best first, and whether each is already scored for the job. No evaluation: pass the ones worth it to score_resumes. Give the job as the job_id of a stored job or as job_text (at least 30 characters; the job is then stored). Costs 1 HireLayer credit per search.
Inputs: city, limit, job_id, job_text, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a recognizably different role: parsing, criteria extraction, evaluation scoring, two proximity searches, and skill normalization. The main potential confusion is between search_resumes/search_jobs (proximity only) and score_resumes (evaluation), but the descriptions explicitly contrast 'no evaluation' versus scoring, which resolves most ambiguity.
All six tools follow a strict snake_case verb_noun pattern (parse_resume, extract_job_criteria, score_resumes, search_resumes, search_jobs, normalize_skills). The verb accurately reflects the action in every case with no mixed conventions.
Six tools is well within the ideal 3-15 range and each maps to a distinct stage of the recruiting workflow (parse, extract, search, score, normalize). No tool feels redundant or trivially thin.
The surface covers the full resume-to-job matching pipeline: parsing, criteria extraction, bidirectional search, scoring, and skill normalization. Minor gaps exist around managing stored artifacts (e.g., listing or deleting stored resumes/jobs by application_id/job_id), but core workflows have no dead ends.
Maintenance
Related MCP Connectors
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
CareerProof MCP gives AI agents direct access to a professional-grade career and workforce intelligence platform. Two namespaces: atlas_* for HR/TA teams (candidate evaluation, batch shortlisting, competency scoring, interview generation, JD analysis, custom eval frameworks, research reports) and ceevee_* for professionals (CV optimization, career positioning, salary intelligence, market reports). Backed by RAG knowledge from 50+ premium research sources (McKinsey, BCG, HBR, Gartner, WEF)
HR and recruiting: score a job description, or generate a structured role profile. No API key.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to recommend jobs, parse candidate profiles, compute semantic skill match scores, and filter opportunities by location through standardized MCP tools.-
- AlicenseAqualityDmaintenanceEnables MCP clients to analyze resumes for ATS compatibility, parse job descriptions, get optimization and roast-style critiques, and generate tailored resumes with shareable preview links.664 npmMIT
- AlicenseNot gradedqualityCmaintenanceA hosted, OAuth-authenticated MCP endpoint exposing 176 tools that let AI assistants read and write jobs, candidates, applications, interviews, scorecards, prospects, talent pools, and imports within an organization's own applicant tracking data, scoped to the signed-in user's existing permissions.MIT
- AlicenseAqualityBmaintenanceTurns any AI assistant into an ATS-optimized resume engine that tailors resumes to job descriptions, validates candidate intake, analyzes gaps, scores matches, and renders DOCX/PDF outputs.9MIT