# Breezy HR MCP

> Breezy HR handles your entire recruitment pipeline directly through any AI agent. Use this MCP to list companies, track open positions, and manage candidate records instantly—all without leaving your chat window. It lets you add new applicants, view application history, or fetch deep metadata for specific roles.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** recruitment, hiring, applicant-tracking, hr-management, candidate-sourcing

## Description

You can connect your HR workflow directly to Breezy HR using this MCP. Instead of jumping between tabs and exporting spreadsheets, your AI agent handles the data retrieval naturally. Ask it to list all companies in your pipeline, then ask for open positions within 'Acme Corp.' You can also check a specific candidate's application history or add new applicants instantly with just names and emails. Vinkius hosts this MCP so you connect once to manage recruiting across multiple services. This lets recruiters pull deep metadata on roles and people, giving them a clear picture of where the hiring process stands.

## Tools

### add_candidate
Creates a brand-new candidate record and adds them to an existing job position.

### get_candidate
Retrieves all personal details for a single, known candidate.

### get_company
Pulls specific data points about one company by its ID.

### get_position
Fetches detailed information for a single job opening.

### list_applications
Lists all historical applications made by a specific candidate across different roles.

### list_candidates
Retrieves multiple candidates who are associated with a single job opening.

### list_companies
Provides an overview of all companies tracked in your Breezy HR account.

### list_positions
Lists every open job position available within a specific company.

## Prompt Examples

**Prompt:** 
```
List all companies in my Breezy HR account.
```

**Response:** 
```
I've retrieved your companies. You have access to: 'Acme Corp' (ID: 5a1b2c) and 'Global Tech' (ID: 3d4e5f). Which one would you like to explore?
```

**Prompt:** 
```
Show me the candidates for the 'Senior Developer' position (ID: pos_123) in company 5a1b2c.
```

**Response:** 
```
Fetching candidates for 'Senior Developer'... I found 3 candidates: Alice Smith, Bob Jones, and Charlie Brown. Would you like the details for any of them?
```

**Prompt:** 
```
Add a new candidate named John Doe with email john@example.com to position pos_123 in company 5a1b2c.
```

**Response:** 
```
Successfully added John Doe to the 'Senior Developer' position. The candidate record has been created in Breezy HR.
```

## Capabilities

### View Company Details
Get specific information about any company in your roster.

### Find Open Positions
Retrieve details for active job openings within a company or across the platform.

### Manage Candidate Records
Add new candidates to your system, or pull up full profiles on existing applicants.

### List Potential Candidates
Get a list of people who fit the criteria for a specific job opening.

### Check Application Status
See every application and its status associated with one candidate.

## Use Cases

### The Pipeline Audit
A recruiter needs a snapshot of all open jobs for Q3. They ask their agent to run `list_companies` first, then iterate through each company's positions using `list_positions`, summarizing the total headcount need.

### The Candidate Deep Dive
A hiring manager needs to know if a candidate applied for another role in the past. The agent runs `get_candidate` and then uses `list_applications` to provide the full history, ensuring no leads slip through the cracks.

### The Quick Intake
A lead comes in via a job board. Instead of filling out forms, the agent runs `add_candidate`, providing the name and email right away to get the applicant into the system immediately.

### Company Comparison
The TA team needs to compare two organizations. They use `get_company` on both IDs, pulling key metadata points side-by-side in a single conversation turn.

## Benefits

- Stop switching tabs. Instead of navigating through multiple dashboards, you can ask your agent to list open positions or fetch candidate details directly within your chat flow.
- Save time on data aggregation. You don't need to manually check application records; the `list_applications` tool pulls a full history for any given candidate instantly.
- Improve onboarding speed. Need to track down a company ID? Use `list_companies` first, then pull up all positions using `list_positions`, keeping your workflow moving.
- Streamline data entry. When you find a promising lead, the agent can use `add_candidate` to input their name and contact details without ever leaving the chat window.
- Gain deep visibility. Use `get_company` or `get_position` to fetch detailed metadata on roles and organizations, helping your team understand the hiring context better.

## How It Works

The bottom line is you talk to your agent using plain language and it executes complex HR lookups through Breezy HR.

1. Subscribe to the MCP and input your Breezy HR API key.
2. Reference the connection in any compatible AI client, like Claude or Cursor.
3. Ask your agent for a specific action, such as 'List all companies' or 'Get details for candidate XYZ'.

## Frequently Asked Questions

**How do I list all companies using the list_companies tool?**
You ask your agent to run `list_companies`. It returns a comprehensive overview of every company you track, giving you their names and IDs for later use.

**What is the difference between get_candidate and list_candidates?**
Use `get_candidate` when you know the candidate's specific ID. Use `list_candidates` if you want a general roster of people associated with a particular job opening.

**Can I add new leads using the add_candidate tool?**
Yes, simply tell your agent to use `add_candidate`. You provide the name and contact info, and it creates the record in Breezy HR for you.

**Do I need list_applications to see a candidate's history?**
Yes. While `get_candidate` gives current details, running `list_applications` shows their full journey—every role and status they applied to historically.

**When calling get_company, what specific API key format should I provide for authentication?**
You must use a valid Breezy HR API Key. This key grants your agent access; it's not the username or password. Make sure the key you pass to the tool is active and has read permissions set up in your account settings.

**What metadata does get_position return about a job opening?**
The get_position tool returns comprehensive details, including required skills, department ID, salary range, and the date it was posted. This depth lets your agent build full job descriptions without extra calls.

**If I run list_positions for many companies, will there be a rate limit?**
Yes, repeated bulk requests can trigger limits. We recommend batching your company IDs and calling the tool in groups of 50 to maintain smooth performance across large datasets.

**If I run list_candidates, how do I handle cases where a position has no applicants yet?**
The tool returns an empty array rather than throwing an error. Your agent should check for this empty response to confirm that zero candidates are currently assigned to that specific role ID.

**Can I see the full details of a specific candidate using their ID?**
Yes! Use the `get_candidate` tool by providing the Company ID, Position ID, and Candidate ID. The agent will return all available profile information and metadata for that candidate.

**How do I list all open job positions for a specific company?**
Simply use the `list_positions` tool with the target Company ID. It will return a list of all job openings associated with that company account.

**Is it possible to add a new candidate to a position directly through the AI?**
Yes, you can use the `add_candidate` action. You'll need to provide the Company ID, Position ID, and the candidate's name (email is optional but recommended) to create the record.