
List applications in Ashby with cursor pagination, optionally filtered by job. Returns applications and page_info.
Get an application's details by ID, including candidate, current stage, and source. Use list_applications to find valid IDs.
Create an application for a candidate on a job. Requires candidateid and jobid. Returns the created application. Use listcandidates and listjobs for IDs.
Update an application's source or credited user. Only provide what should change. Use list_applications to find valid IDs.
Move an application to a different interview stage. Returns the updated application. Use listinterviewstages to find valid stage IDs.
Change the source attributed to an application. Returns the updated application. Use list_sources to find valid source IDs.
List the history of an application (stage changes and other events) with cursor pagination. Use list_applications to find valid IDs.
List feedback submissions for an application. Use list_applications to find valid IDs.
Submit feedback for an application using a feedback form. Requires the form definition ID, submitting user ID, and field submissions matching the form. Use listfeedbackforms for the form structure.
List candidates in Ashby with cursor pagination. Returns candidates and page_info with a cursor for the next page.
Get a candidate's full profile by ID, including contact info, tags, and application IDs. Use listcandidates or searchcandidates to find valid IDs.
Search candidates by email and/or name. Provide at least one of email or name. Returns matching candidates.
Create a new candidate. Requires a name; email, phone, social links, location, and source are optional. Returns the created candidate.
Update a candidate's profile. All fields except candidateid are optional, only provide what should change. Use listcandidates to find valid IDs.
Add a note to a candidate's profile. Returns the created note. Use list_candidates to find valid IDs.
List notes on a candidate's profile with cursor pagination. Use list_candidates to find valid IDs.
Add an existing tag to a candidate. Returns the updated candidate. Use listcandidatetags for tag IDs and list_candidates for candidate IDs.
Remove a tag from a candidate. Returns the updated candidate. Use listcandidatetags for tag IDs and list_candidates for candidate IDs.
List candidate tags in the organization with cursor pagination. Returns tags and page_info.
Create a new candidate tag with the given title. Returns the created tag.
Upload and parse a resume for a candidate. Provide the file as base64. Parsed data only fills fields missing on the candidate. Use list_candidates to find valid IDs.
Get a temporary download URL for a file by its handle, e.g. a candidate's resumeFileHandle.handle from get_candidate. Returns a presigned URL.
List interview types configured in Ashby with cursor pagination. Returns interviews and page_info.
Get an interview type's details by ID. Use list_interviews to find valid IDs.
List scheduled interviews with cursor pagination, optionally filtered by application. Returns schedules and page_info.
Cancel a scheduled interview. Returns the updated schedule. Use listinterviewschedules to find valid IDs.
List the interview stages for an interview plan. Provide an interviewplanid (found on a job via get_job's interviewPlanIds). Returns ordered stages.
Get an interview stage's details by ID. Use listinterviewstages to find valid IDs.
List jobs in Ashby with cursor pagination, optionally filtered by status (Open, Closed, Archived, Draft). Returns jobs and page_info.
Get a job's details by ID, including status, location, department, hiring team, and interview plan IDs. Use list_jobs to find valid IDs.
Search jobs by title. Returns matching jobs.
Create a new job. Requires a title and teamid (department). Returns the created job. Use listdepartments to find valid team IDs.
Update a job's title, location, department, or employment type. Only provide what should change. Use list_jobs to find valid IDs.
Set a job's status (Draft, Open, Closed, Archived). Returns the updated job. Use list_jobs to find valid IDs.
List published job postings (the public-facing listings for jobs). Returns postings with links and location info.
Get a job posting's details by ID. Use listjobpostings to find valid IDs.
Update a job posting's title, description, or listed status. Only provide what should change. Use listjobpostings to find valid IDs.
List offers in Ashby with cursor pagination, each with its latest version. Returns offers and page_info.
Get an offer's details by ID, including its latest version (salary, start date, status). Use list_offers to find valid IDs.
List openings (headcount/requisitions) in Ashby with cursor pagination. Returns openings and page_info.
Get an opening's details by ID, including its latest version (jobs, locations, hiring team). Use list_openings to find valid IDs.
Search openings by their identifier. Returns matching openings.
Create a new opening (headcount/requisition). All fields are optional. Returns the created opening. Use list_departments for team IDs.
Update an opening's identifier, description, or target dates. Only provide what should change. Use list_openings to find valid IDs.
List Ashby users (recruiters, hiring managers, interviewers). Returns users and page_info.
Get an Ashby user's details by ID. Use list_users to find valid IDs.
Search for an Ashby user by email address. Returns matching users.
List departments in Ashby. Returns departments and page_info.
Get a department's details by ID. Use list_departments to find valid IDs.
List locations in Ashby. Returns locations and page_info.
Get a location's details by ID, including address. Use list_locations to find valid IDs.
List candidate sources (how candidates entered the pipeline) configured in Ashby.
List archive reasons (rejection reasons) configured in Ashby.
List custom field definitions configured in Ashby with cursor pagination. Returns custom fields and page_info.
Get a custom field definition's details by ID. Use listcustomfields to find valid IDs.
List feedback form definitions configured in Ashby with cursor pagination. Returns forms and page_info.
Get a feedback form definition's structure (sections and fields) by ID. Use listfeedbackforms to find valid IDs.
List projects (talent pools) in Ashby with cursor pagination. Returns projects and page_info.
Get a project's details by ID. Use list_projects to find valid IDs.
Search projects by title. Returns matching projects.
Fetch a report's results synchronously by report ID. Returns column names and data rows. Times out after 30s; use generate_report for large or slow reports. Find the report ID in the report's URL in Ashby.
Generate a report's results asynchronously. Call without requestid to start generation (returns a requestid and status inprogress), then call again with that requestid to poll until status is complete. Use for large reports that time out in get_report.
Validate Ashby credentials by verifying API access. Returns success status and the API key title.

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}It's an MCP server that lets your agents access data and functionality from Ashby via tools. Your agents can invoke these tools to pull candidate profiles, advance applications through pipeline stages, post new job openings, submit interview feedback, and more.
Ashby doesn't offer an official MCP server (they plan to release one soon), but you can also use one from a third-party platform, like Merge Agent Handler.
The use cases naturally depend on the agent you've built, but here are a few common ones:
Here are some of the most commonly used tools:
list_candidates: returns candidate records filtered by job, stage, or source. Useful for agents that need to survey a pipeline before deciding what to act onget_application: retrieves a single application with its current stage, linked candidate, and activity history. Call this when an agent needs full context on one applicantadvance_application_stage: moves an application to a new stage in the interview plan. Use this when an agent automates pipeline progression based on screening resultscreate_candidate: creates a new candidate record from external data. Good for workflows that source prospects in another tool and push them into Ashbysubmit_interview_feedback: attaches a scorecard or note to an application. Helpful when an agent compiles structured feedback after an interviewlist_openings: returns active job openings and their requisition details. Useful for agents that match candidates to roles or report on open headcountThere are several reasons to use Merge Agent Handler's Ashby MCP server over building or using an alternative:
You can take the following steps:
1. Create or log into your Merge Agent Handler account.
2. Install the Merge CLI by running pipx install merge-api, then run merge configure to link the CLI to your Merge account and merge login to authenticate your session.
3. Register the Agent Handler MCP server with Claude Code by running claude mcp add --transport http agent-handler https://ah-api.merge.dev/mcp, then open Claude Code and run /mcp to confirm agent-handler appears with a connected status.
4. Select agent-handler from the MCP list. This opens a browser window where you select which integrations to authenticate. Choose Ashby and complete the auth flow. Merge stores and manages the credentials going forward.
5. Open a Claude Code session and start querying Ashby data directly. The first time you use an Ashby tool, a Magic Link may appear to complete connector authentication.
If you want to connect Merge Agent Handler's Ashby MCP with internal or customer-facing agentic products, you can follow the steps in our docs.
Yes, Merge for Workforce lets your employees connect Claude, ChatGPT, Microsoft Copilot, Cursor, and other MCP-compatible AI tools to Ashby without bypassing IT governance.
Instead of setting up direct connections with personal credentials that IT can't monitor or revoke, each employee authenticates through Merge and gets individual credentials tied to their identity. A recruiter can ask Claude to check where a candidate sits in the pipeline, log interview feedback, or post a new opening, all within the permissions IT has defined.
IT also provisions access by role or group via SCIM. A recruiter, for example, gets Ashby access to advance candidates and log feedback, Gmail to manage candidate outreach, and Slack to coordinate with the hiring panel; while a hiring manager gets Ashby access to review applications and scorecards, Google Calendar to schedule interviews, and Zoom to run them.
Every tool call an employee's AI makes to Ashby is also inspected against your DLP rules and logged to a searchable audit trail, giving security teams full visibility into what data was accessed and by whom.
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now