Connect your AI Agents to Greenhouse in minutes
Available tools
list_applications
List applications with optional filters (job_id, status, timestamps). Returns candidate info, stage, status, and assignments. Supports pagination up to 500 per page.
get_application
Get detailed application by ID including candidate profile, current stage, status, rejection details, jobs, assignments, custom fields, and activity timeline.
create_application
Create a job application for a candidate. Requires candidate_id with at least one email. Use discover_custom_and_required_fields('application') to see org-specific requirements. Returns application with assigned stage.
advance_application
Advance application to next stage in hiring workflow. Requires from_stage_id matching current stage. Use get_application to verify stage and get_job_stages for valid transitions.
reject_application
Reject an active application with specified reason. Use list_reject_reasons for available options. Sets status to 'rejected'. Can be reversed with unreject_application.
unreject_application
Restore rejected application to active status. Application must currently be 'rejected'. Returns to previous stage and clears rejection details. Use get_application to verify status first.
move_application
Move application to any stage (forward or backward) within same job. Requires from_stage_id and to_stage_id. Unlike advance, allows non-sequential moves. Use get_job_stages for available stages.
transfer_application
Transfer application to different job. Requires target_job_id. Optionally specify target_stage_id (defaults to first stage). Preserves candidate info and history. Cannot transfer prospects.
check_hire_readiness
Validate application meets all hiring prerequisites. Checks status, offer completeness, approvals, and job openings. Returns readiness report with blocking issues and resolution steps. Use before hire_application.
add_application_note
Add note to application with visibility control (admin_only, private, or public). Records feedback and observations. Returns note_id and complete note data with timestamps.
list_candidates
List all candidates in Greenhouse with optional pagination and filtering by job_id, created_before/after, updated_before/after timestamps. Returns comprehensive candidate data including personal information (name, title, company), contact details (emails, phones, addresses), social media profiles, employment and education history, assigned recruiter and coordinator, candidate tags, attachments (resumes, cover letters), all associated applications with current stages, custom field values, and activity timestamps. Supports up to 500 candidates per page for efficient bulk retrieval.
get_candidate
Retrieve comprehensive candidate profile by ID including personal information (name, title, company), complete contact details (all emails, phones, addresses), social media profiles (LinkedIn, GitHub, etc.), employment history with dates and descriptions, education background, profile photo, all attachments (resumes, cover letters, portfolios), assigned recruiter and coordinator, candidate tags for categorization, all associated applications with current stages and statuses, custom field values, privacy settings, and activity timestamps. Essential for reviewing candidate qualifications before making hiring decisions.
create_candidate
Create a new candidate profile in Greenhouse with personal information, contact details, and optional application. Requires on_behalf_of user ID for authentication. According to Greenhouse API, NO candidate fields are strictly required - you can create a candidate with minimal information. Recommended fields: first_name, last_name, email (or email_addresses array). Convenience fields automatically converted: 'email' string → email_addresses array, 'phone' string → phone_numbers array, 'prospect' boolean → prospect application. Optionally specify job_id to create application simultaneously, or omit to create prospect. Supports custom fields, employment history, education, addresses, social media profiles, and attachments. Use discover_custom_and_required_fields('candidate') to identify organization-specific requirements. Returns complete candidate profile with assigned ID.
update_candidate
Update an existing candidate's profile information including personal details (name, title, company), contact information (emails, phones, addresses), social media profiles, employment history, education background, recruiter and coordinator assignments, tags, custom field values, and privacy settings. All fields are optional - only provide fields you want to update. Changes are immediately reflected in all associated applications. Use get_candidate first to see current values. Returns updated candidate profile with new timestamps.
merge_candidates
Merge two duplicate candidate records into a single profile, keeping the primary candidate and transferring all data from the duplicate. Requires primary_candidate_id (candidate to keep) and duplicate_candidate_id (candidate to merge and delete). All applications, attachments, notes, tags, and activity history from the duplicate are transferred to the primary candidate. The duplicate candidate is permanently deleted after merge. Use this to consolidate duplicate profiles and maintain clean candidate data. Irreversible operation - verify IDs carefully before merging. Returns the merged primary candidate with combined data.
add_candidate_tags
Add one or more tags to a candidate for categorization, filtering, and organization. Tags are labels like 'Senior Engineer', 'Referral', 'Diversity Candidate' that help organize and search candidates. Requires candidate_id and array of tag names. If a tag doesn't exist in Greenhouse, it will be automatically created. Tags are case-insensitive. Useful for bulk tagging, pipeline segmentation, and reporting. Returns success confirmation with count of tags added.
remove_candidate_tags
Remove one or more tags from a candidate. Requires candidate_id and array of tag names to remove. Tags are case-insensitive. If a specified tag doesn't exist on the candidate, it will be silently skipped (no error). Useful for cleaning up outdated tags, removing incorrect categorizations, or updating candidate status. Does not delete the tags from Greenhouse - only removes the association with this candidate. Returns success confirmation with count of tags removed.
add_candidate_note
Add a note to a candidate for recording recruiter observations, interview feedback, or internal communications. Requires candidate_id, note body text, user_id (user creating the note), and visibility ('admin_only' for admins only, 'private' for note creator and admins, or 'public' for all users with candidate access). Notes are permanently associated with the candidate and visible across all their applications. Optionally specify on_behalf_of user ID for auditing. Returns note_id, candidate_id, and complete note data including timestamps and visibility settings. Essential for maintaining candidate evaluation history.
list_jobs
List all job postings in Greenhouse with optional pagination and timestamp-based filtering (created_before/after, updated_before/after). Returns comprehensive job data including job title, requisition ID, status (open/closed/draft), departments and offices, hiring team members, job stages with interview plans, custom fields, openings count, and confidentiality settings. Supports up to 500 jobs per page. Essential for discovering available positions and understanding job workflows before creating applications.
get_job
Retrieve comprehensive details about a specific job by ID including job title, requisition ID, status (open/closed/draft), complete job description, departments and offices, hiring team (recruiters, coordinators, hiring managers), all job stages with interview plans and milestones, custom field values, openings count and details, confidentiality settings, approval flows, and job posts. Use this to understand job structure and workflow before creating applications or moving candidates through stages. Essential for validating job_id and stage_id parameters.
create_job
Create a new job posting in Greenhouse by copying from a template job. Requires template_job_id (existing job to copy from) and on_behalf_of user ID. The new job inherits all settings from the template including stages, hiring team, departments, offices, and custom fields. Optionally specify job name, requisition_id, and other job properties to override template values. Use discover_custom_and_required_fields('job') first to identify organization-specific required fields. Returns complete job record with assigned job_id and all inherited settings.
update_job
Update an existing job's information including job name, requisition ID, status, departments, offices, hiring team assignments, custom field values, and confidentiality settings. All fields are optional - only provide fields you want to update. Changes are immediately reflected for all associated applications and candidates. Use get_job first to see current values. Returns updated job with new timestamps.
get_job_stages
Retrieve all hiring stages and workflow steps for a specific job including stage names, IDs, interview plans, milestones, and stage ordering. Each stage represents a step in the hiring process (e.g., 'Application Review', 'Phone Screen', 'Technical Interview', 'Offer'). Use this to understand valid stage transitions before advancing or moving applications. Essential for validating from_stage_id and to_stage_id parameters in application workflow operations. Returns ordered list of stages with complete configuration.
list_job_openings
List all job openings (requisitions/headcount slots) for a specific job including opening ID, status (open/closed), opening date, close date, close reason, and custom opening fields. Each opening represents a specific position to fill within the job. Multiple openings allow tracking separate hires for the same role. Use this to verify opening availability before hiring candidates or to understand headcount allocation. Returns list of all openings with current status and metadata.
create_job_opening
Create a new job opening (requisition/headcount slot) for a specific job to track individual hires. Requires job_id and on_behalf_of user ID. Optionally specify opening_id (external requisition number), status ('open' or 'closed'), open_date, close_date, and custom opening fields. Each opening represents one position to fill. Use this to add headcount capacity before hiring candidates. Use discover_custom_and_required_fields('job_opening') to identify organization-specific requirements. Returns created opening with assigned ID.
update_job_opening
Update an existing job opening's information including status (open/closed), opening_id (external requisition number), open_date, close_date, close_reason, and custom opening fields. Use this to close openings when positions are filled, reopen closed openings, or update opening metadata. All fields are optional - only provide fields you want to update. Returns updated opening with new values.
get_job_approval_flows
Retrieve all approval workflows configured for a specific job including approval flow names, required approvers, approval stages, and current approval status. Approval flows control who must approve candidates before they can be hired (e.g., hiring manager approval, budget approval, executive approval). Use this to understand approval requirements before attempting to hire candidates. Essential for troubleshooting hire_application failures related to pending approvals. Returns list of approval flows with approver details and status.
list_departments
List all departments in the organization including department names, IDs, parent-child relationships, external IDs, and child department hierarchies. Departments organize jobs and users by functional area (e.g., Engineering, Sales, Marketing). Use this to discover valid department_id values for job creation and filtering. Returns complete department hierarchy with parent and child relationships.
get_department
Retrieve detailed information about a specific department by ID including department name, parent department, child departments, external ID, and complete hierarchical relationships. Use this to understand department structure before assigning jobs or filtering candidates by department.
create_department
Create a new department in the organization to organize jobs and users by functional area. Requires department name. Optionally specify parent_id to create nested department hierarchy and external_id for integration with external systems. Department names must be unique within the organization. Requires admin-level permissions. Use discover_custom_and_required_fields('department') to see field requirements. Returns created department with assigned ID.
update_department
Update an existing department's information including name, parent department relationship, and external ID. All fields are optional - only provide fields you want to update. Changes are immediately reflected for all associated jobs and users. Use get_department first to see current values. Returns updated department with new values.
list_offices
List all office locations in the organization including office names, IDs, physical locations, primary contact users, parent-child relationships, external IDs, and child office hierarchies. Offices represent physical locations where employees work (e.g., San Francisco HQ, New York Office, Remote). Use this to discover valid office_id values for job creation and user assignment. Returns complete office hierarchy with location details.
get_office
Retrieve detailed information about a specific office by ID including office name, physical location, primary contact user, parent office, child offices, external ID, and complete hierarchical relationships. Use this to understand office structure before assigning jobs or users to locations.
create_office
Create a new office location in the organization to track where employees work and jobs are located. Requires office name. Optionally specify location (city, state, country), primary_contact_user_id for the office manager, parent_id to create nested office hierarchy, and external_id for integration with external systems. Office names must be unique. Requires admin-level permissions. Use discover_custom_and_required_fields('office') to see field requirements. Returns created office with assigned ID.
update_office
Update an existing office's information including name, location, primary contact user, parent office relationship, and external ID. All fields are optional - only provide fields you want to update. Changes are immediately reflected for all associated jobs and users. Use get_office first to see current values. Returns updated office with new values.
list_sources
List all candidate sources available in the system for tracking where candidates come from (e.g., LinkedIn, Indeed, Referral, Career Site, Agency). Sources help measure recruiting channel effectiveness and ROI. Each source has an ID and public name. Use this to discover valid source_id values for candidate and application creation. Returns complete list of all configured sources with IDs for attribution.
list_close_reasons
List all reasons available for closing job openings to track why positions are no longer active (e.g., 'Hire - New Headcount', 'Position Eliminated', 'Filled Internally', 'Budget Frozen'). Close reasons help analyze hiring outcomes and workforce planning. Use this to discover valid close_reason_id values for hire_application and update_job_opening operations. Returns complete list of all configured close reasons with IDs.
list_reject_reasons
List all reasons available for rejecting candidates to track why applications are declined (e.g., 'Underqualified', 'Position Filled', 'Compensation Mismatch', 'Failed Assessment', 'Culture Fit'). Reject reasons help analyze candidate quality and improve sourcing strategies. Use this to discover valid rejection_reason_id values for reject_application operations. Returns complete list of all configured rejection reasons with IDs and types.
list_custom_fields
List all custom field definitions configured in the system for extending standard Greenhouse objects with organization-specific data. Custom fields can be added to candidates, jobs, applications, and other objects. Each field has a name, type (text, dropdown, date, etc.), possible values for dropdowns, and whether it's required. Use this to discover available custom fields before creating or updating objects. Returns complete list of all custom field definitions with types, options, and requirements.
list_tags
List all candidate tags available in the system for categorizing and organizing candidates (e.g., 'Senior Engineer', 'Diversity Candidate', 'Referral', 'Passive Candidate'). Tags enable flexible filtering, searching, and reporting on candidate pools. Each tag has an ID and name. Use this to discover existing tags before adding tags to candidates. Returns complete list of all configured candidate tags with IDs.
discover_custom_and_required_fields
Discover comprehensive field requirements for creating Greenhouse objects including core required fields, recommended fields, optional fields, and organization-specific custom fields. Supports candidate, job, application, department, office, and user object types. Returns complete field metadata with types, requirements, validation rules, example values, and usage notes. Essential tool to call BEFORE creating objects to understand all field requirements and avoid validation errors. Prevents trial-and-error by providing complete field specifications upfront.
list_scorecards
List all interview scorecards in Greenhouse with optional pagination and filtering by application_id, candidate_id, interview_id, and timestamps. Scorecards contain interviewer feedback including ratings, recommendations (strong_yes/yes/no/strong_no), interview questions with answers, and overall assessment. Use this to analyze interview feedback across candidates or track specific interviewer assessments. Supports up to 500 scorecards per page. Returns comprehensive scorecard data with interviewer details and submission timestamps.
get_scorecard
Retrieve detailed information about a specific interview scorecard by ID including interviewer name and details, interview type, submission timestamp, overall recommendation (strong_yes/yes/no/strong_no), individual attribute ratings with focus areas, interview questions with candidate answers and interviewer notes, and complete feedback. Use this to review detailed interview feedback before making hiring decisions.
get_application_scorecards
Retrieve all interview scorecards for a specific application to see complete interview feedback from all interviewers. Returns list of scorecards with interviewer names, interview stages, submission timestamps, overall recommendations, ratings, and detailed feedback. Use this to aggregate interview feedback before advancing candidates or making hiring decisions. Essential for understanding team consensus on candidate qualifications.
get_scorecard_summary
Calculate aggregate statistics and summary metrics for all scorecards associated with an application. Returns total scorecard count, submitted scorecard count, average numeric rating across all attributes, and breakdown of recommendations by type (strong_yes/yes/no/strong_no counts). Use this to quickly assess overall interview feedback without reviewing individual scorecards. Helpful for identifying strong candidates with consistent positive feedback or candidates with mixed reviews requiring discussion.
list_users
List all Greenhouse users with optional pagination and filtering by employee_id, created_before/after, updated_before/after timestamps. Returns comprehensive user data including name, email, employee ID, site admin status, deactivated status, linked candidate IDs, and timestamps. Users represent team members who can access Greenhouse (recruiters, hiring managers, coordinators, admins). Use this to discover valid user_id values for on_behalf_of parameters and user assignments. Supports up to 500 users per page.
get_user
Retrieve detailed information about a specific Greenhouse user by ID including full name, email address, employee ID, site administrator status (site_admin), account deactivated status, linked candidate IDs, creation and update timestamps. Use this to verify user permissions before using them in on_behalf_of parameters, check if users have admin privileges, or understand user-candidate relationships.
create_user
Create a new Greenhouse user account for a team member. Requires first_name, last_name, email, and on_behalf_of user ID (must have admin privileges). Optionally specify employee_id for HR system integration and linked_candidate_ids to associate user with candidate profiles. New users receive account credentials and can be assigned roles and permissions separately. Requires admin-level permissions. Use discover_custom_and_required_fields('user') to see field requirements. Returns created user with assigned user_id.
update_user
Update an existing Greenhouse user's information including first_name, last_name, email, employee_id, and linked_candidate_ids. All fields are optional - only provide fields you want to update. Cannot change site_admin or deactivated status through this endpoint (use enable_user/disable_user instead). Requires on_behalf_of user ID with admin privileges. Returns updated user with new values.
disable_user
Disable a Greenhouse user account to revoke system access while preserving user data and history. Disabled users cannot log in but their past activities, notes, and assignments remain visible. Requires on_behalf_of user ID with site administrator privileges (site_admin=true). Use this for offboarding team members or temporarily suspending access. Can be reversed with enable_user. Returns updated user with deactivated=true status.
enable_user
Re-enable a previously disabled Greenhouse user account to restore system access. User can log in again with existing credentials and permissions. Requires on_behalf_of user ID with site administrator privileges (site_admin=true). Use this to restore access for returning team members or after temporary suspensions. Returns updated user with deactivated=false status.
get_user_permissions
Retrieve basic permissions information for a specific user including site_admin status (full system access), deactivated status (account active/inactive), and user name. Site admins have unrestricted access to all Greenhouse features and data. Use this to verify if a user has sufficient privileges before using them in on_behalf_of parameters. Note: Detailed role-based permissions require separate user roles API endpoints.
invite_user
Create a new Greenhouse user account and automatically send invitation email with login credentials. Requires email, first_name, last_name, and on_behalf_of user ID (must have admin privileges). Optionally specify role_ids to assign roles during creation. The invited user receives an email with account setup instructions and password creation link. Requires admin-level permissions. Use discover_custom_and_required_fields('user') to see field requirements. Returns success confirmation with user_id.
validate_credential
Validate Greenhouse credentials. Verifies credentials during setup.
How to set up Merge Agent Handler
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}FAQs on using Merge's Greenhouse MCP server
FAQs on using Merge's Greenhouse MCP server
How can I use the Greenhouse MCP server?
Here are just a few use cases:
- Interview scheduling: Your agent can coordinate interview availability by checking candidate responses, reviewing interviewer calendars, and proposing optimal time slots. It can then create the interview in Greenhouse and send calendar invites once approved
- Application screening: Your agent can periodically review new applications, extract key qualifications from resumes, and flag high-priority candidates based on predefined criteria. It can also move candidates through pipeline stages and add screening notes automatically
- Candidate status updates: Your agent can monitor candidates who haven't received updates in a while and draft status update emails to keep them engaged. For instance, it can detect candidates stuck in a stage for over a week and propose follow-up communications
- New hire onboarding prep: Your agent can monitor for accepted offers in Greenhouse and trigger onboarding workflows in your HRIS (e.g., BambooHR, Workday). For example, it can create the employee record in the HRIS, pre-fill details from the candidate profile, and notify IT to start procuring/provisioning equipment and application access
- Reference check automation: Your agent can identify candidates ready for reference checks in Greenhouse, extract reference contact details, and initiate reference check requests through your reference checking platform (e.g., Checkr, Xref). Your agent can then log the results back in Greenhouse once the check is complete
What are popular tools for Greenhouse’s MCP server?
Here are just a few popular tools across data types:
Applications
- <code class="blog_inline-code">list_applications</code>
- <code class="blog_inline-code">get_application</code>
- <code class="blog_inline-code">create_application</code>
- <code class="blog_inline-code">advance_application</code>
- <code class="blog_inline-code">reject_application</code>
Candidates
- <code class="blog_inline-code">list_candidates</code>
- <code class="blog_inline-code">get_candidate</code>
- <code class="blog_inline-code">create_candidate</code>
- <code class="blog_inline-code">Add_candidate_note</code>
Jobs
- <code class="blog_inline-code">get_job_stages</code>
- <code class="blog_inline-code">list_job_openings</code>
- <code class="blog_inline-code">create_job_opening</code>
- <code class="blog_inline-code">get_job_approval_flows</code>
What makes Merge Agent Handler’s Greenhouse MCP server better than alternative Greenhouse MCP servers?
Merge Agent Handler provides platform-level capabilities that aren’t inherent to MCP alone:
- Enterprise-grade security and DLP: All tool inputs and outputs are scanned by a security gateway with configurable data loss prevention rules to block, redact, or mask sensitive data
- Real-time observability and auditability: Every tool call is logged with a complete, fully-searchable audit trail, enabling teams to debug, review, and manage agent behavior
- Managed authentication and permissions: Merge handles dynamic authentication flows, credential storage, and permission validation for registered users, reducing integration complexity
- Broad and customizable tool coverage: Merge’s Greenhouse connector comes with 50+ tools out of the box. You can also easily add your own or modify existing ones to fit your exact requirements
Can I set security rules for Greenhouse tool calls in Merge Agent Handler?
Yes, you can set a wide range of security rules for Greenhouse tool calls in Merge Agent Handler. Here are just a few examples:
- Block candidate PII in tickets: Prevent your agents from including candidate social security numbers, home addresses, or phone numbers when creating tickets or notes in other systems based on Greenhouse data
- Redact salary information: Automatically mask compensation details and salary ranges from Greenhouse job requisitions or offer letters before your agents share candidate information across systems
- Log sensitive searches: Track and audit whenever your agents search Greenhouse for candidates with specific demographic information or protected characteristics
- Block external email domains: Prevent your agents from sending candidate data to email addresses outside your organization's domain when drafting outreach messages
- Redact interview feedback: Automatically strip confidential interviewer comments or sensitive evaluation notes before your agents summarize candidate profiles or create reports
- Block unauthorized data exports: Prevent your agents from bulk extracting candidate records or application data that could violate data retention policies
How can I add tools to Merge Agent Handler’s Greenhouse MCP server?
Here are the steps to get started:
1. Create your Agent Handler account. Sign up for a free Merge Agent Handler account here.
2. Set up a Tool Pack. Navigate to "Tool Packs" in the dashboard sidebar and click "Create New Tool Pack." Add the Greenhouse connector from the list of available MCP connectors and give your Tool Pack a descriptive name (e.g., "Recruiting Automation Pack").
3. Configure authentication. Choose between individual authentication, where each user provides their own Greenhouse credentials, and shared authentication, which uses organization-level credentials for all users.
4. Register a user identity. Navigate to "Registered Users" and create an entry. This represents the identity (either human or system) that’ll perform actions through your agent.
5. Associate the Tool Pack with your agent. Save your Tool Pack and connect it to your agent using the MCP entry URL provided in the Tool Pack settings.
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
