Vayora MCP tools for candidates and search
Find people already in your Vayora database, read what the desk knows about them, rank them against a role or a plain-English brief, and add someone new without creating a duplicate.
Written by the Vayora team. Updated 29 October 2026.
The tools
8 tools: 6 read and 2 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.
search_candidatesFree-text search across name, email, title, company, location, skills, tags, notes and CV text.
Takes: query, limit=20 (max 50)
Returns: Matching candidates, each with the fields the query matched, in order of how much that field says about the person.
Credits: None
get_candidateOne candidate's full record.
Takes: candidate_id
Returns: Contact details, current title and company, skills, the recruiter's tags and their recent notes.
Credits: None
get_candidate_briefThe desk's distilled intel on a candidate, for pre-call prep.
Takes: candidate_id
Returns: What they want, hard constraints such as notice and salary floor, what moves them, what clients said, each with an evidence quote. Says so if no brief exists.
Credits: None
get_candidate_cvThe candidate's CV text and the files on record.
Takes: candidate_id
Returns: Whether a CV exists, the parsed text fenced as untrusted, its length and the list of attached files.
Credits: None
match_candidates_to_roleRank the people in your database against a saved role and say why each fits.
Takes: requisition_id, limit=10 (max 50)
Returns: A status (ok, no_criteria, no_role_embedding or not_found) and, when ok, ranked suggestions each with a met, unmet or uncertain checklist.
Credits: None
match_candidates_to_briefRank the database against a plain-English description, when no role exists yet.
Takes: brief, limit=10 (max 50)
Returns: A status, the criteria read from the brief so they can be checked, and ranked suggestions with their checklists.
Credits: None
create_candidateAdd a person to the database.
Takes: name, email='', phone='', linkedin_url='', current_title='', current_company='', location='', notes='', tags=None, source='mcp'
Returns: The candidate, with created true or false. A person already on the book, matched on email, LinkedIn URL or phone and never on name alone, comes back unchanged.
Credits: None
add_candidate_noteAdd a note to a candidate's record, attributed to the signed-in user.
Takes: candidate_id, content, requisition_id='', is_private=False
Returns: The saved note. With a role id it is filed against that role's pipeline; without one it sits on the person.
Credits: None
Two kinds of search, kept apart
search_candidates is a substring match. It finds people you can describe: a name, a title, a skill, a town, a word from a CV or a note. It does not score anyone. When the question is who fits, the assistant should use match_candidates_to_role or match_candidates_to_brief, which run the same matching engine the role screen uses: keyword recall, vector similarity, rank fusion and a rerank, with a checklist of the role's must-haves marked met, unmet or uncertain for every name.
The matching tools say when they cannot score honestly. A role with no must-haves extracted from its job description returns a status that tells the recruiter to add one, rather than a list of noisy guesses. A brief too vague to pull must-haves from comes back the same way, and the criteria the engine read out of the brief are returned so the recruiter can correct how their sentence was understood before anyone is contacted.
What the desk has learned
get_candidate returns the record with the recruiter's own tags and recent notes, which is where the useful part lives: what the person wants, why they said no last time, whether to approach again. get_candidate_brief returns the distilled version, with each claim tied to a quote from the record, and says so plainly when no brief has been generated yet. get_candidate_cv returns the parsed CV text fenced between markers, so the assistant treats the CV as data to read and never as instructions to follow.
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.
- Who in my database fits the Senior Financial Controller role for Harlow Group, and why?
- Show me everyone with IFRS and Manchester on their record, then open the strongest two.
- I need an enterprise AE, SaaS, London, around 90 to 110k base. Who do we already know?
- Summarise what Priya Shah wants from her next move and add a note that she is free to talk on Thursday.
Common questions
- Can the assistant see a candidate's CV?
- Yes, through get_candidate_cv, which returns the parsed text and the list of files on record. The text is fenced and marked as written by the candidate, so an instruction hidden in a CV is read as content and is not something the assistant should act on.
- Will create_candidate make duplicates?
- No. It matches on email, LinkedIn URL or phone, and never on name alone, because two different people can share a name. A match returns the existing record and changes nothing, so the assistant can tell the recruiter they are already on the book.
- Does matching invent a fit when the data is thin?
- It refuses instead. If a role has no must-haves, or a brief is too vague to extract any, the tool returns a status saying so and what to add. The recruiter sees a reason in place of a confident percentage.
- Can it edit or delete a candidate?
- Not through MCP. The candidate tools read, add a person and add a note. Changes to an existing record and deletions are done in the app.
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.