Vayora MCP tools for roles and pipeline
Read open roles and their pipelines, spot candidates who have stalled, set up a new role, move a candidate between stages, submit someone to a client and draft the client's progress report.
Written by the Vayora team. Updated 29 October 2026.
The tools
9 tools: 6 read and 3 write. A read tool works on a connection made read-only. A write tool needs the person to have ticked Allow changes when they connected.
list_open_rolesOpen, paused and draft roles. Closed and archived ones are left out.
Takes: limit=25 (max 100)
Returns: Each role's id, title, department, seniority, client, status and creation date, with a count.
Credits: None
get_roleOne role's full record.
Takes: requisition_id
Returns: The role, including the stages on its pipeline board.
Credits: None
get_role_pipelineA pipeline snapshot for one role.
Takes: requisition_id
Returns: Counts per stage, each candidate's current stage and days in stage, and a total.
Credits: None
list_stuck_candidatesCandidates sitting too long in a stage that is not final.
Takes: days_threshold=7, include_applied=False, limit=50 (max 200)
Returns: The candidates, their roles and stages, and how long they have been there.
Credits: None
list_submissionsSubmissions to clients, with status and any client feedback.
Takes: requisition_id='', client_id='', candidate_id='', status='', limit=50
Returns: Each submission's candidate, client, role, status (submitted through placed, rejected or withdrawn), feedback and date.
Credits: None
draft_client_search_reportDraft the progress report for a client on one role.
Takes: requisition_id, since_days=7
Returns: The facts used and a draft with headline, progress, submissions and next steps, grounded in real data only. Nothing is sent.
Credits: None
create_roleSet up a new role for a client.
Takes: client_id, title, location='', job_description='', fee='', source=''
Returns: The role with created true or false, a duplicate flag, and warnings for anything set up alongside it that did not go through.
Credits: None
move_candidate_stageMove a candidate to another stage in a role's pipeline.
Takes: candidate_id, requisition_id, to_stage, note=''
Returns: The change id, from stage, to stage and time, or an error listing the role's stages when the move is refused.
Credits: None
Changes data, so hosts are told it is not additive.
submit_candidate_to_clientPut a candidate forward to a client, optionally against a role.
Takes: candidate_id, client_id, requisition_id='', summary='', rate_quoted=None
Returns: The submission id and status.
Credits: None
Visible at once to contacts invited to the client's portal.
Reading the pipeline
get_role_pipeline answers how a search is looking: how many candidates sit at each stage and a flat list of who is where, with days in stage. list_stuck_candidates is the slipping-work question across every role, with a threshold of seven days by default and a switch for including people who have only applied, since stale applications have their own detector. list_submissions shows what has gone to clients and what they said, filtered by role, client, candidate or status.
Changing it, and what stays in the app
create_role sets a role up the way the New role form does, so the job description is read for must-haves and the matching tools work on it shortly afterwards. It will not create a duplicate: a role with the same title for the same client, not closed or archived and made in the last 30 days, is returned with duplicate true. No MCP tool edits, closes or deletes a role. Those stay in the app.
move_candidate_stage takes a column on the role's board by its key, and matches everyday names such as screening or placed to the board's key. Rejected and withdrawn are not accepted and nothing moves. submit_candidate_to_client creates the submission record the client portal and reports read, the same as the Submit to client button. It does not email or notify anyone by itself, although a submission is seen at once by the client contacts invited to the portal, which is why hosts treat it as a tool that sends outside the agency.
What to ask
These are the kind of messages a recruiter types into Claude or ChatGPT once Vayora is connected. The assistant chooses the tools itself.
- How is the Head of Finance search looking? Where is everyone sitting?
- Who has been stuck in a stage for more than ten days, across all my roles?
- Set up a Financial Controller role for Harlow Group in Leeds using this job description.
- Move Priya Shah to interview on the controller role and note that the client asked for Thursday.
Common questions
- Can the assistant reject a candidate?
- No. move_candidate_stage moves people between the stages on a role's board. Rejected and withdrawn are refused, with the role's valid stages listed and nothing moved. Rejections stay a decision made in the app.
- Does submitting a candidate email the client?
- Not by itself. It creates the submission record that the portal and reports read. Contacts invited to the client's portal can see it straight away, so it is worth confirming before the assistant runs it.
- Can it close or delete a role?
- No. create_role only creates. Editing, closing, archiving and deleting a role are done in the app, which keeps the MCP surface small enough to audit.
- Does create_role work on every plan?
- It is refused, with nothing written, for a workspace whose plan does not include clients and roles or shortlisting and matching, and for any team member the app itself would not let set up a role, including one whose admin has turned off managing roles and pipeline.
Every tool acts as the person who connected it, inside their own workspace. The MCP overview covers connecting, the read and write split and limits. The developers page has the API and webhooks, integrations lists the rest of what Vayora connects to, and ATS or CRM for a recruitment agency explains why the records sit in one place. To try it on your own book, start a free trial.