# HireLayer MCP Server **Resume parsing, resume scoring and talent pool search for AI agents.** The official [Model Context Protocol](https://modelcontextprotocol.io) server for [HireLayer](https://hirelayer.co). 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. [![npm version](https://img.shields.io/npm/v/hirelayer-mcp?color=4f46e5)](https://www.npmjs.com/package/hirelayer-mcp) [![CI](https://github.com/hirelayer/hirelayer-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/hirelayer/hirelayer-mcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![MCP](https://img.shields.io/badge/MCP-compatible-4f46e5)](https://modelcontextprotocol.io) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=hirelayer&config=eyJ1cmwiOiJodHRwczovL2hpcmVsYXllci5jby9tY3AifQ%3D%3D) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=hirelayer&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fhirelayer.co%2Fmcp%22%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_server-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=hirelayer&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fhirelayer.co%2Fmcp%22%7D&quality=insiders) [![Add to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=hirelayer&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImhpcmVsYXllci1tY3AiXSwiZW52Ijp7IkhJUkVMQVlFUl9BUElfS0VZIjoieW91ci1hcGkta2V5In19)

> "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 - [What you can do](#what-you-can-do) - [Quick start](#quick-start) - [Install in your MCP client](#install-in-your-mcp-client) - [Tools](#tools) - [Example prompts](#example-prompts) - [Pricing and credits](#pricing-and-credits) - [Data and privacy](#data-and-privacy) - [Troubleshooting](#troubleshooting) - [FAQ](#faq) ## 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 1. **Add the server URL** `https://hirelayer.co/mcp` in your AI app, or click a one-click install button above. 2. **Sign in to HireLayer** when your app asks, and allow access. No account yet? [Sign up for free](https://hirelayer.co/auth/signup): 50 credits a month, no card required. 3. **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/`](examples). The repository ships a [`.mcp.json`](.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** | `claude mcp add --transport http hirelayer https://hirelayer.co/mcp`, then `/mcp` to sign in | | **Cursor** | Click **Install in Cursor** above, or add `{ "mcpServers": { "hirelayer": { "url": "https://hirelayer.co/mcp" } } }` to `~/.cursor/mcp.json` | | **VS Code** | Click **Install in VS Code** above, or add `{ "servers": { "hirelayer": { "type": "http", "url": "https://hirelayer.co/mcp" } } }` to `.vscode/mcp.json` | | **Codex CLI** | `codex mcp add hirelayer --url https://hirelayer.co/mcp`, then `codex mcp login hirelayer` | 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](https://hirelayer.co/auth/signup), then copy your key from **Dashboard → API keys** and replace `your-api-key` below.

Claude Code

```bash claude mcp add hirelayer --env HIRELAYER_API_KEY=your-api-key -- npx -y hirelayer-mcp ```

Claude Desktop

Open **Settings → Developer → Edit Config** and add the server to `claude_desktop_config.json`: ```json { "mcpServers": { "hirelayer": { "command": "npx", "args": ["-y", "hirelayer-mcp"], "env": { "HIRELAYER_API_KEY": "your-api-key" } } } } ``` Restart Claude Desktop.

Cursor

Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): ```json { "mcpServers": { "hirelayer": { "command": "npx", "args": ["-y", "hirelayer-mcp"], "env": { "HIRELAYER_API_KEY": "your-api-key" } } } } ```

VS Code (GitHub Copilot)

Add this to `.vscode/mcp.json`. VS Code asks for your API key and stores it securely: ```json { "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}" } } } } ```

Windsurf

Add this to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "hirelayer": { "command": "npx", "args": ["-y", "hirelayer-mcp"], "env": { "HIRELAYER_API_KEY": "your-api-key" } } } } ```

OpenAI Codex CLI

```bash codex mcp add hirelayer --env HIRELAYER_API_KEY=your-api-key -- npx -y hirelayer-mcp ```

Gemini CLI

```bash gemini mcp add -e HIRELAYER_API_KEY=your-api-key hirelayer npx -y hirelayer-mcp ```

Cline, Roo Code, Zed, LM Studio and other clients

Any client that runs stdio MCP servers works with this command and environment variable: - Command: `npx -y hirelayer-mcp` - Environment: `HIRELAYER_API_KEY=your-api-key` Cline users can also ask Cline to install the server: [`llms-install.md`](llms-install.md) has the steps.

Docker

```bash docker build -t hirelayer-mcp . docker run -i --rm -e HIRELAYER_API_KEY=your-api-key hirelayer-mcp ``` In 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 | |---|---|---|---| | `parse_resume` | Resume Parser | Parses a resume or CV into structured JSON: contact details, experience, education, languages, skills and the full text, stored under an `application_id` | A local `file_path`, a public `file_url` or the `resume_text`. Accepts PDF, DOC, DOCX, ODT, RTF, TXT, HTML, Markdown, PPT, PPTX, ODP, XLS, JPG, PNG or BMP files under 4.5 MB. | | `extract_job_criteria` | 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_id` | Job description text, at least 30 characters | | `score_resumes` | 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. `precise_ranking` re-ranks the 10 best with a reason each | The job as `job_text` (optionally with your own `criteria`) or a `job_id`, and each resume as `text` or an `application_id`; at least one resume of 30 characters or more | | `search_resumes` | 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 `score_resumes` | A `job_id` or `job_text` | | `search_jobs` | Job Recommendations | Finds the stored open jobs closest to a resume. Proximity only | An `application_id` or `resume_text` | | `normalize_skills` | 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](CHANGELOG.md). The server also ships **prompts** that clients show as ready-made commands: | Prompt | What it does | |---|---| | `screen_candidates` | Parses the resume files, scores every resume against the job in one call with a precise ranking, and writes a shortlist | | `summarize_resume` | Parses one resume and writes a recruiter summary | | `normalize_skills` | Normalizes a skills section and groups it by domain | ### How screening works ```mermaid 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] ```

Example output from score_resumes

Trimmed to one resume and one criterion: ```json { "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.pdf` and 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/` against `examples/job-senior-react-developer.md`." ## Pricing and credits | Tool | Credits | |---|---| | `parse_resume` | 1 per resume, 0 for a file already stored | | `extract_job_criteria` | Free (a new text for a job already scored evaluates its scores again, 1 credit each) | | `score_resumes` | 1 per resume evaluated, 0 for a job-resume pair already scored; 1 more per call with `precise_ranking` | | `search_resumes`, `search_jobs` | 1 per search | | `normalize_skills` | 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 | See [hirelayer.co/pricing](https://hirelayer.co/pricing) | ## 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_resume` reads only the file you name. HireLayer stores the resume in your account under its `application_id`, keeps the original file and returns a link to it in `resume.info_resume.url`. On the Enterprise plan, set `do_not_store_data: true` in 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](https://hirelayer.co/privacy-policy) and the [security policy](SECURITY.md). 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 | |---|---|---|---| | `HIRELAYER_API_KEY` | Yes | | Your HireLayer API key | | `HIRELAYER_BASE_URL` | No | `https://hirelayer.co` | API base URL, for testing | ## Troubleshooting | Symptom | Fix | |---|---| | `HIRELAYER_API_KEY is not set` | Add the `env` block with your key to the client config, then restart the client. | | `HireLayer API returned 401` | The key is wrong or revoked. Copy it again from **Dashboard → API keys**. | | `HireLayer API returned 403 (insufficient_credits)` | You have used your monthly credits. Wait for the reset or upgrade your plan. | | `HireLayer API returned 403 (enterprise_plan_required)` | `do_not_store_data` needs the Enterprise plan. Call again without it if storing the resume is fine. | | `HireLayer API returned 410` | You run a 1.x version, which calls retired endpoints. Update to the latest version with `npx -y hirelayer-mcp@latest`. | | 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. | | `npx` not found or an old Node.js | Install Node.js 20 or later from [nodejs.org](https://nodejs.org). | | The file is not found | Use an absolute path, for example `/Users/me/Downloads/cv.pdf` rather than `~/Downloads/cv.pdf`. | To debug, run the server in the MCP Inspector: ```bash HIRELAYER_API_KEY=your-api-key npx @modelcontextprotocol/inspector npx -y hirelayer-mcp ``` ## FAQ **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](https://hirelayer.co/api-docs). **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](https://hirelayer.co/api-docs), the [OpenAPI spec](https://hirelayer.co/openapi.json) and [`llms.txt`](https://hirelayer.co/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 ```bash 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.js ``` See [CONTRIBUTING.md](CONTRIBUTING.md). Report bugs in [GitHub issues](https://github.com/hirelayer/hirelayer-mcp/issues) and vulnerabilities as described in [SECURITY.md](SECURITY.md). ## Links - Website: [hirelayer.co](https://hirelayer.co) - API reference: [hirelayer.co/api-docs](https://hirelayer.co/api-docs) - OpenAPI: [hirelayer.co/openapi.json](https://hirelayer.co/openapi.json) - Docs for agents: [hirelayer.co/llms.txt](https://hirelayer.co/llms.txt) - Contact: [contact@hirelayer.co](mailto:contact@hirelayer.co) ## License [MIT](LICENSE)