Kenso MCP tools

Roles roles

The jobs a recruiting workspace hires for, each with a candidate pipeline by stage, and the extra roles a recruiting campaign also hires for. Extract reads a job link into a draft role.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through roles_read and changes through roles_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.

Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.

Operations: candidates-create, create, delete, candidates-events, candidates-export, extract, candidates-find, campaign-roles-get, get, candidates-list, list, campaign-roles-replace, candidates-update, update

candidates-create

Write. Early access: needs recruiting on for the workspace. POST https://api.ken.so/v1/roles/{roleId}/candidates

Path: roleId

Body (json): campaignId integer, contactId integer, email string, firstName string, lastName string, linkedinUrl string, referredByContactId integer, source string

Add a person to a role's pipeline at stage sourced. Pass contact_id for a contact, or the person's email or linkedin_url to create them.

POST /api/v1/roles/{roleId}/candidates. Staff. Sends Ken-Version 1.1 and X-Ken-Actor:
agent. Requires campaigns edit. Without contact_id the person (first_name, last_name,
email, linkedin_url) becomes a lead of campaign_id, else of the role's first
recruiting campaign; the usual dedupe, blocklist and lead credits apply. email is
required unless that campaign is LinkedIn-only, where linkedin_url is enough. An email or
linkedin_url of someone already a contact elsewhere in the workspace adds that contact.
campaign_id must be a recruiting campaign of this role. referred_by_contact_id names the contact
who referred them and makes source referral; source is manual or referral. Returns
201 with the candidate. Errors: not_found (role_not_found, contact_not_found,
referrer_not_found, campaign_not_found); conflict (already_candidate,
contact_exists, not_recruiting, campaign_not_linked); validation_failed
(campaign_required when the role has no recruiting campaign; email required when
the campaign sends email and no email was sent).

create

Write. Early access: needs recruiting on for the workspace. POST https://api.ken.so/v1/roles

Body (json): ats object, companyDomain string, companyName string, description string, hiringContact string, jobUrl string, location string, mustHaves array, niceToHaves array, pay object, remotePolicy string, seniority string, status string, title string

Create a role: a job the workspace hires for. Status starts open. title is required; fields takes the rest. To fill it from a job link, run extract first.

POST /api/v1/roles. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Requires
campaigns edit. title: 1 to 200 characters. fields (all optional): company_name,
company_domain (a domain, website or work email), job_url (an http(s) URL),
description, must_haves and nice_to_haves (lists of up to 20 short lines), pay {min,
max, currency (ISO 4217 such as USD), period (year, month, day, hour)}, location,
remote_policy (onsite, hybrid, remote), seniority (such as Senior), hiring_contact
(who candidates hear from, such as a name and title; up to 200 characters), status
(open, paused, filled, closed), ats {provider (bullhorn, ashby, greenhouse, lever),
job_id, connection_id}. Returns 201 with the role. Errors: validation_failed naming
the field (required, invalid, out_of_range); conflict with detail ats_job_mapped when
another live role maps the same ATS job.

delete

Write. Early access: needs recruiting on for the workspace. DELETE https://api.ken.so/v1/roles/{roleId}

Path: roleId

Delete a role. Its candidates and their history stay; its campaigns keep running.

DELETE /api/v1/roles/{roleId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires campaigns edit. Soft delete; returns 204. The role leaves list and get; its
candidates and their events stay readable, and a campaign that hires for it keeps
running unchanged. An unknown role or another workspace's is not_found with detail
role_not_found.

candidates-events

Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/roles/{roleId}/candidates/{candidateId}/events

Path: roleId, candidateId

Read a candidate's stage history, oldest first.

GET /api/v1/roles/{roleId}/candidates/{candidateId}/events. Staff. Sends Ken-Version
1.1 and X-Ken-Actor: agent. Requires the campaigns page. Each event: id, fromStage
(absent on the first), toStage, source, moveKind (automatic, manual, ats),
actorUserId, reason, occurredAt. Errors: not_found with detail candidate_not_found.

candidates-export

Write. Early access: needs recruiting on for the workspace. POST https://api.ken.so/v1/roles/{roleId}/candidates/export

Path: roleId

Body (json): stages array

Export a role's candidates as CSV text, up to 5,000 rows. stages limits it to those stages; absent or [] exports every stage.

POST /api/v1/roles/{roleId}/candidates/export. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Requires the campaigns page and export access (admin or editor).
Returns {format: csv, rowCount, csv}, plus truncated: true when the role has more
than 5,000 candidates and the rest were cut (the Kenso app exports up to 50,000). The
header is candidate_id, contact_id, first_name, last_name, email, linkedin_url,
title, company, location, stage, stage_changed_at, source, campaign_id,
referred_by_contact_id, ats_candidate_id, ats_application_id, created_at. Each export
writes an audit-log entry. Errors: not_found with detail role_not_found;
validation_failed naming stages, or with detail too_many_rows over 50,000 candidates
(pass stages to narrow it).

extract

Write. Early access: needs recruiting on for the workspace. POST https://api.ken.so/v1/roles/extract

Body (json): text string, url string

Read a job link or pasted text into a draft role. Nothing is saved. Send url (a job or application page) or text (the role in the user's words; it wins).

POST /api/v1/roles/extract. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires campaigns edit. Takes up to a minute. Returns a draft with the create fields
it found (title, companyName, companyDomain, jobUrl, description, mustHaves,
niceToHaves, pay, location, remotePolicy, seniority), plus missing (the fields the
page did not give) and questions (one plain question per missing field, to ask the
user). Review the draft with the user, then save it with roles(operation='create').
Errors: validation_failed with detail page_unreadable when Kenso cannot read the page
(paste the text instead); 503 extraction_unavailable when the model is down (retry
later).

candidates-find

Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/role-candidates

Query: contactId integer

List the roles a contact is a candidate for, one row per role.

GET /api/v1/role-candidates?contactId=. Staff. Sends Ken-Version 1.1 and X-Ken-Actor:
agent. Requires the campaigns page. Returns the candidates on every role of the
workspace, deleted roles included, oldest first, with the fields of
roles(operation='candidates-list'); an empty list when the contact is in no pipeline.

campaign-roles-get

Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/roles

Path: campaignId

Read the roles a campaign hires for: its own role and up to 3 extra roles.

GET /api/v1/campaigns/{campaignId}/roles. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Requires the campaigns page. Returns {primaryRoleId, extraRoleIds}.
A sales campaign has no primaryRoleId and an empty extraRoleIds. Errors: not_found
with detail campaign_not_found.

get

Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/roles/{roleId}

Path: roleId

Read one role with its campaigns and pipeline counts by stage.

GET /api/v1/roles/{roleId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires the campaigns page. The role has the fields of roles(operation='list'). An
unknown role, a deleted one or another workspace's is not_found with detail
role_not_found.

candidates-list

Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/roles/{roleId}/candidates

Path: roleId

Query: cursor string, limit integer, stage string

List a role's candidates with their stage and where they came from. stage filters (comma = OR) by any of the ten pipeline stages.

GET /api/v1/roles/{roleId}/candidates. Staff. Sends Ken-Version 1.1 and X-Ken-Actor:
agent. Requires the campaigns page. Stages: sourced, contacted, replied, interested,
screen_booked, submitted, interviewing, offer, hired, not_a_fit. limit 1 to 100
(default 50); pass pagination.nextCursor back as cursor with the same stage. Each
candidate: id, roleId, contactId, campaignId, stage, stageChangedAt, source (campaign,
manual, referral, ats, import), person {firstName, lastName, title, company,
linkedinUrl, email, location}, ats {candidateId, applicationId, pushedAt},
referredByContactId, studio {views, ctaClicks, formSubmits, lastEventAt}, createdAt.
Empty fields are left out. studio is the person's engagement with their own Studio
pages: human views, CTA clicks and form submits (scanner hits not counted), and the
time of the latest of them. A page nobody has opened yet gives {views: 0, ctaClicks:
0, formSubmits: 0, lastEventAt: null}; studio is left out when the person has no
Studio page. Readable after the role is deleted.

list

Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/roles

Query: cursor string, limit integer, q string, status string

List the workspace's roles with their campaigns and pipeline counts by stage. status filters (comma = OR): open, paused, filled, closed. q matches the title or company.

GET /api/v1/roles. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Requires the
campaigns page. status absent = every status. limit 1 to 100 (default 50); pass
pagination.nextCursor back as cursor with the same filters. Each role: id, title,
companyName, companyDomain, jobUrl, description, mustHaves, niceToHaves, pay {min, max,
currency, period (year, month, day, hour)}, location, remotePolicy (onsite, hybrid,
remote), seniority, hiringContact (who candidates hear from), status, ats {provider,
jobId, connectionId}, campaignIds (the live campaigns that hire for it, as primary or
extra role), stageCounts (all ten stages: sourced, contacted, replied, interested,
screen_booked, submitted, interviewing, offer, hired, not_a_fit), createdAt,
updatedAt. Empty fields are left out.

campaign-roles-replace

Write. Early access: needs recruiting on for the workspace. PUT https://api.ken.so/v1/campaigns/{campaignId}/roles

Path: campaignId

Body (json): extraRoleIds array

Set a recruiting campaign's extra roles, in order. [] removes every extra role.

PUT /api/v1/campaigns/{campaignId}/roles. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Requires campaigns edit. extra_role_ids: up to 3 live role ids,
not the campaign's own role (change that on the campaign). Returns {primaryRoleId,
extraRoleIds}.
Errors: not_found (campaign_not_found, role_not_found); conflict with detail
not_recruiting for a sales campaign; validation_failed (primary_role,
too_many_roles).

candidates-update

Write. Early access: needs recruiting on for the workspace. PATCH https://api.ken.so/v1/roles/{roleId}/candidates/{candidateId}

Path: roleId, candidateId

Body (json): stage string

Move a candidate to a stage by hand. Any stage; the move is recorded in their events.

PATCH /api/v1/roles/{roleId}/candidates/{candidateId}. Staff. Sends Ken-Version 1.1
and X-Ken-Actor: agent. Requires campaigns edit. stage: sourced, contacted, replied,
interested, screen_booked, submitted, interviewing, offer, hired or not_a_fit. A move
by hand skips the automatic rules (it can go back a stage). The same stage changes
nothing. Returns the candidate. Errors: not_found with detail candidate_not_found;
validation_failed naming stage; conflict with detail move_refused.

update

Write. Early access: needs recruiting on for the workspace. PATCH https://api.ken.so/v1/roles/{roleId}

Path: roleId

Body (json): ats object, companyDomain string, companyName string, description string, hiringContact string, jobUrl string, location string, mustHaves array, niceToHaves array, pay object, remotePolicy string, seniority string, status string, title string

Change a role. Send only the fields that change; null clears one. changes takes title and the create fields (pay and ats replace the whole object).

PATCH /api/v1/roles/{roleId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires campaigns edit. changes keys: title, company_name, company_domain, job_url,
description, must_haves, nice_to_haves, pay {min, max, currency, period}, location,
remote_policy, seniority, hiring_contact, status, ats {provider, job_id,
connection_id}. title and status cannot be null; null or blank hiring_contact clears
it. A campaign that hires for the role gets the new facts in its Role brief
qualification prompt. Returns the role. Errors: not_found with detail role_not_found;
validation_failed naming the field; conflict with detail ats_job_mapped.