Kenso MCP tools

LinkedIn linkedin

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through linkedin_read and changes through linkedin_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: create-connect-session, delete, get, linkedin-sequences-get, segment-linkedin-sequences-get, linkedin-sequences-get-version, segment-linkedin-sequences-get-version, list, linkedin-sequences-list-versions, segment-linkedin-sequences-list-versions, preview-sales-navigator, linkedin-sequences-replace, segment-linkedin-sequences-replace, reset-ramp, resolve-sales-navigator, linkedin-sequences-restore-version, segment-linkedin-sequences-restore-version, linkedin-sequences-save-version, segment-linkedin-sequences-save-version, update

create-connect-session

Write. POST https://api.ken.so/v1/linkedin-accounts/connect-sessions

Body (json): importConnections boolean, linkedInAccountId integer, networkOnly boolean

Start a hosted connect or reconnect session. Returns 201. Omit linkedin_account_id to connect a new seat. Pass it to reconnect.

POST /api/v1/linkedin-accounts/connect-sessions. Public. Sends Ken-Version 1.1.
Requires Delivery edit, or approve_own_sends (the Client template) for the
caller's own LinkedIn. A seat-limit refusal is 402 plan_limit_reached.
A reconnect keeps the member who connected the seat (they approve its
touches) while that member is still in the workspace.
A client seat connects only its own LinkedIn: reconnecting another
member's seat is 403 not_your_linkedin, and a new seat while it holds one
is 409 reconnect_instead (the detail names the id to reconnect).
import_connections (boolean, DEV-5778): a new seat imports its connections into Accounts.
Stored only where the linkedin_connections_import flag is on; ignored on a reconnect.
network_only (boolean, DEV-8542): true connects a network-only seat (synced for warm
paths, never in a campaign). Needs warm_paths_v2 (400 feature_off); ignored on a reconnect.
A Network member's seat is always network-only (DEV-8704).

delete

Write. DELETE https://api.ken.so/v1/linkedin-accounts/{linkedinAccountId}

Path: linkedinAccountId

Delete a LinkedIn account. Returns 204. Requires Delivery edit access (owners, admins and editors by default).

DELETE /api/v1/linkedin-accounts/{linkedinAccountId}. Public. Sends Ken-Version 1.1.

get

Read. GET https://api.ken.so/v1/linkedin-accounts/{linkedinAccountId}

Path: linkedinAccountId

Return one LinkedIn account in the current workspace. A missing or cross-workspace id is not_found.

GET /api/v1/linkedin-accounts/{linkedinAccountId}. Public. Sends Ken-Version 1.1.
Requires Delivery view.
The account includes unipileAccountId, statusChangedAt, and createdDatetime,
plus invitesToday, messagesToday, visitsToday, invitesSent30d, acceptRate,
usedBy, lastActionAt and lastActionType as on linkedin(operation="list"),
and the safety fields
(invitesLast7Days, pendingInvites, health, rampInviteCap, safetyEnabled),
products, workingHoursSchedule and tagIds. connectedByMemberId is the member
who connected the seat (null on older seats). networkOnly as on list.
Ramp: rampPlansEnabled is true once Kenso runs LinkedIn on the per-action
ramp. While it is true the account also has rampStartedAt and ramp, one row
per action (invite, message, visit, follow, reaction, comment, endorse,
accept) with action, todayCap, start, stepPerWeek, ceiling, weekIndex and
fullVolumeOn (the date todayCap reaches the ceiling). While it is false
they are omitted and rampStage and rampInviteCap show the old ladder.
safetyHolds: the seat's active safety holds ({ scope: all_writes |
invites | invite_notes, until, reason, source }), [] when none, as on list.

linkedin-sequences-get

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/linkedin-sequence

Path: campaignId

Return the campaign LinkedIn sequence.

GET /api/v1/campaigns/{campaignId}/linkedin-sequence. Public. Sends Ken-Version 1.1.

segment-linkedin-sequences-get

Read. GET https://api.ken.so/v1/segments/{segmentId}/linkedin-sequence

Path: segmentId

Return the segment LinkedIn sequence.

GET /api/v1/segments/{segmentId}/linkedin-sequence. Public. Sends Ken-Version 1.1.

linkedin-sequences-get-version

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/linkedin-sequence/versions/{versionId}

Path: campaignId, versionId

Return one campaign LinkedIn sequence version. Snapshot step types and conditions are lowercase snake_case.

GET /api/v1/campaigns/{campaignId}/linkedin-sequence/versions/{versionId}. Public.
Sends Ken-Version 1.1. Requires Campaigns view.

segment-linkedin-sequences-get-version

Read. GET https://api.ken.so/v1/segments/{segmentId}/linkedin-sequence/versions/{versionId}

Path: segmentId, versionId

Return one segment LinkedIn sequence version. Snapshot step types and conditions are lowercase snake_case.

GET /api/v1/segments/{segmentId}/linkedin-sequence/versions/{versionId}. Public.
Sends Ken-Version 1.1. Requires Campaigns view.

list

Read. GET https://api.ken.so/v1/linkedin-accounts

Query: cursor string, limit integer

List LinkedIn accounts in the current workspace. Requires Delivery view.

GET /api/v1/linkedin-accounts. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.
Accounts include unipileAccountId, statusChangedAt, and createdDatetime.
connectedByMemberId is the member who connected the seat; touches that
send from it wait on that member's approval. Null on older seats.
networkOnly (DEV-8542): the seat only lends its network (synced, never
in a campaign or sending on its own).
Usage (each omitted when it cannot be read):
- invitesToday, messagesToday, visitsToday: actions counted against the
  seat's daily budget today (the seat's local day, or the trailing 24
  hours when the rolling window is on). messagesToday includes InMails.
- invitesSent30d: invites sent in the last 30 days.
- acceptRate: the share of those invites accepted so far, a fraction 0-1;
  omitted when invitesSent30d is 0.
- usedBy: { campaigns: [{ id, name, status }], accounts }: campaigns are
  the live campaigns (scheduled, launching or sending) the seat is
  assigned to. accounts is true when the member who connected the seat
  owns at least one account in the workspace, because an account's
  LinkedIn touches default to the seat its owner connected.
- lastActionAt, lastActionType (DEV-3977): when the seat last completed
  an outbound action (its newest confirmed campaign step or Accounts-lane
  touch, UTC) and which: visit | invite | message | inmail | withdraw |
  follow | reaction | comment | endorse. A person's replies from the
  Inbox do not count. Omitted together when the seat has none.
Safety (DEV-1295; omitted together when it cannot be read; computed even
while safetyEnabled is false, when Kenso shows but does not enforce them):
- invitesLast7Days / weeklyInviteCap: invites in the rolling 7 days and
  the cap (at most 100).
- pendingInvites / pendingInviteCap: invitations still pending (the
  larger of Kenso's and Unipile's count) and the cap (450); at the cap the
  seat sends no new invites.
- health: { status: healthy | low_acceptance, acceptRate, sample,
  changedAt } over invites sent 3 to 30 days ago; low_acceptance (below
  20% on 40 or more) caps invites at 5 a day until 25%.
- rampStage / rampInviteCap: ramp stage and today's ramp invite cap.
- safetyEnabled: whether the weekly, pending and low-acceptance caps apply.
products: { premium, salesNavigator, recruiter, checkedAt } from Unipile,
refreshed daily; omitted until first checked.
workingHoursSchedule: { mon..sun: { open, start, end } } as Kenso applies
them in the seat's timezone (defaults Mon-Fri 08:00-18:00); workingHours
is the stored JSON string.
tagIds: ids of the workspace tags on the seat, ascending, [] when none
(omitted when they cannot be read). Tag a seat with tags(operation="assign")
and entity_type linkedin_account; read the names with tags(operation="list").
Ramp: rampPlansEnabled is true once Kenso runs LinkedIn on the per-action
ramp. While it is true the account also has rampStartedAt and ramp, one row
per action (invite, message, visit, follow, reaction, comment, endorse,
accept) with action, todayCap, start, stepPerWeek, ceiling, weekIndex and
fullVolumeOn (the date todayCap reaches the ceiling). While it is false
they are omitted and rampStage and rampInviteCap show the old ladder.
safetyHolds (DEV-10566): the holds Kenso has on the seat right now, []
when none (or when they cannot be read), at most one per scope, each
{ scope, until, reason, source }. scope: all_writes (no outreach at all) |
invites (no new invites) | invite_notes (invites go out without a note).
until is when the hold ends (ISO 8601 UTC). reason says why in plain words;
source is the check that placed it (account_warning, invite_streak,
provider_streak, note_quota, reconnect_quiet; new codes may appear).
Kenso places and lifts holds itself; no operation clears one.

linkedin-sequences-list-versions

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/linkedin-sequence/versions

Path: campaignId

Query: cursor string, limit integer

List saved versions of a campaign LinkedIn sequence, newest first. limit is 1 to 100. Omit it for 20. Requires Campaigns view.

GET /api/v1/campaigns/{campaignId}/linkedin-sequence/versions. Public. Sends Ken-Version 1.1.

segment-linkedin-sequences-list-versions

Read. GET https://api.ken.so/v1/segments/{segmentId}/linkedin-sequence/versions

Path: segmentId

Query: cursor string, limit integer

List saved versions of a segment LinkedIn sequence, newest first. limit is 1 to 100. Omit it for 20. Requires Campaigns view.

GET /api/v1/segments/{segmentId}/linkedin-sequence/versions. Public. Sends Ken-Version 1.1.

preview-sales-navigator

Read. Early access: needs sales_navigator on for the workspace. POST https://api.ken.so/v1/linkedin-accounts/{linkedinAccountId}/sales-navigator/preview

Path: linkedinAccountId

Body (json): url string

Preview a Sales Navigator search or list through your own LinkedIn seat. Returns kind (people or companies), total and the first 25 rows. Writes nothing.

POST /api/v1/linkedin-accounts/{linkedinAccountId}/sales-navigator/preview. Internal.
Sends Ken-Version 1.1. Listed to members only in a workspace with the
sales_navigator feature (the route is 404 without it). Needs the import
permission.

linkedin_account_id is a seat you connected yourself: another member's seat
is not_found. url is a Sales Navigator lead search, lead list, account search
or account list copied from the browser (https://www.linkedin.com/sales/...).
Items carry name, title, company, linkedinUrl, companyLinkedinUrl and, for
companies, domain (only companies with a domain can become accounts).
A seat without Sales Navigator is 409 sales_navigator_required: reconnect it
with Sales Navigator in Settings > LinkedIn. A disconnected seat is 409
invalid_state.
Import people with contacts(operation="contact-imports-create",
source="sales_navigator", ...) and companies with
accounts(operation="create-sales-navigator-account-import", ...).

linkedin-sequences-replace

Write. PUT https://api.ken.so/v1/campaigns/{campaignId}/linkedin-sequence

Path: campaignId

Body (json): instruction string, steps array

Replace the campaign LinkedIn sequence. Requires Campaigns edit access (owners, admins and editors by default).

PUT /api/v1/campaigns/{campaignId}/linkedin-sequence. Public. Sends Ken-Version 1.1.

Each step requires step_type: profile_visit, connection_request, message, in_mail,
follow, like_post, endorse_skill, comment_post, or voice_note. condition_type is none, clicked,
replied_positive, accepted, not_accepted, or engaged. Omitted condition_type defaults to none.

accepted runs the step only for a lead who accepted the connection request; not_accepted only
for a lead who did not accept within the campaign's not_accepted_after_days LinkedIn setting.
Both need a connection_request earlier in the lane. wait_from_condition true also counts the
step's wait_days from the moment the condition came true (the lead accepted, or the invite
expired): the step goes once both the wait after the anchor email and the wait after the
condition have passed. "1 day after they connect" is a message with condition_type accepted,
wait_days 1 and wait_from_condition true. Only accepted and not_accepted take it. Omitted
means false.

LinkedIn bodies take {firstName}, {lastName}, {companyName}, {localizedGreeting}, the campaign's
custom variables, and {lastEmailSubject}: the subject of the latest email this campaign sent the
lead, without "Re:". Add a fallback after a pipe for leads with no email yet:
{lastEmailSubject|what you're building}.

Engagement steps (follow, like_post, endorse_skill, comment_post) and the engaged condition
need the workspace's linkedin_engagement flag; without it the save is rejected with 400.
Turning the flag off also stops saved engagement steps: each skips with engagement_disabled
and the lane continues. follow, like_post and endorse_skill take no variants, and a body on them is
ignored (never sent). like_post likes the prospect's newest original post from the last 30 days
that takes reactions. endorse_skill only works between
1st-degree connections, so put it after the connection_request with condition_type accepted.
For comment_post, Ken writes the comment in the background on the prospect's newest
original post from the last 30 days. A comment not written within 6 hours skips with
comment_unavailable, and a workspace out of credits skips with insufficient_credits.
comment_post's body is optional guidance for Ken (max 500 characters), not the comment
itself. Each step skips (the lane continues)
when there is nothing to act on. engaged waits for the prospect to read or react to one of
our LinkedIn messages, so it needs a message step earlier in the lane.

requires_approval (like_post, endorse_skill and comment_post only) holds each like,
endorsement or comment for a person's approval in the approvals queue
(campaign.linkedin_engagement items), showing the exact comment Ken wrote. Omitted on a
new like_post, endorse_skill or comment_post step it is true; omitted on an existing step
it keeps the stored value; false lets Ken act without asking. Ignored on every other step
type. An action nobody approves within 3 days skips with approval_expired, and a skipped
one with not_approved; the lane continues either way.

note_mode (connection_request only) is template (body is the note) or ai (Ken writes
each note for approval; needs the linkedin_ai_notes feature, body must be empty).
Omitted note_mode keeps the stored value. ai_instructions guides Ken's notes, up to
1,000 characters. A note vs no-note test is a second variant with note_mode template
and an empty body.

voice_note (needs the linkedin_voice_notes feature) sends a LinkedIn voice note that Ken
records for each lead. LinkedIn takes voice notes between 1st-degree connections only.
body is the required text fallback (at most 1,900 characters), sent when the note cannot
go. voice holds provider (deepgram or elevenlabs), voice_id (a voice from the workspace's
voice list), speed (0.5 to 1.5, Deepgram only), words_mode (ken_writes: instructions
guide Ken, up to 1,000 characters; script: script is the words, up to 900 characters),
model (haiku or sonnet) and match_lead_language. A voice that is unknown, early access or
another workspace's import is refused with 400. voice is only allowed on voice_note steps.

instruction: the person's request behind this save, in their words ("make step 2
shorter"), kept as agent-reported in the steps' edit history (2,000 characters).
Omit it when no person asked; never invent one.

segment-linkedin-sequences-replace

Write. PUT https://api.ken.so/v1/segments/{segmentId}/linkedin-sequence

Path: segmentId

Body (json): instruction string, steps array

Replace the segment LinkedIn sequence. Requires Campaigns edit access (owners, admins and editors by default).

PUT /api/v1/segments/{segmentId}/linkedin-sequence. Public. Sends Ken-Version 1.1.
Step fields match the campaign LinkedIn sequence.
note_mode, ai_instructions, requires_approval and the voice_note step's voice included.

instruction: the person's request behind this save, in their words ("make step 2
shorter"), kept as agent-reported in the steps' edit history (2,000 characters).
Omit it when no person asked; never invent one.

reset-ramp

Write. POST https://api.ken.so/v1/linkedin-accounts/{linkedinAccountId}/ramp/reset

Path: linkedinAccountId

Restart a LinkedIn account's ramp from today: every action goes back to its start value. Requires Delivery edit access. 409 invalid_state while rampPlansEnabled is false.

POST /api/v1/linkedin-accounts/{linkedinAccountId}/ramp/reset. Public. Sends Ken-Version 1.1.
Keeps each action's start, step per week and ceiling and moves rampStartedAt to now.
Returns the account with rampPlansEnabled, rampStartedAt and ramp (one row per
action: action, todayCap, start, stepPerWeek, ceiling, weekIndex, fullVolumeOn).
409 invalid_state while LinkedIn still uses the ramp-up stages (rampPlansEnabled false).

resolve-sales-navigator

Read. Early access: needs sales_navigator on for the workspace. POST https://api.ken.so/v1/linkedin-accounts/{linkedinAccountId}/sales-navigator/resolve

Path: linkedinAccountId

Body (json): url string

Check what a Sales Navigator link opens, without calling LinkedIn. Returns type (search, list, lead, account or other), kind, readable and seatHasSalesNavigator.

POST /api/v1/linkedin-accounts/{linkedinAccountId}/sales-navigator/resolve.
Internal. Sends Ken-Version 1.1. Listed to members only in a workspace with
the sales_navigator feature (the route is 404 without it). Needs the import
permission. DEV-8886.

Reads the url alone and spends none of the seat's Sales Navigator reads.
type: search (a lead or account search, saved or not), list (a lead or
account list), lead (one person's lead page), account (one company's
account page) or other (a page that lists nothing, such as the home page).
kind: people or companies, omitted for other. readable: true for a search
or a list, the links the preview, the imports and the Sales Navigator
workflow source (companies only) read. seatHasSalesNavigator: the seat's
Sales Navigator as LinkedIn last reported it, omitted until first checked.
A url that is not a Sales Navigator link is validation_failed on url.
linkedin_account_id is a seat you connected yourself: another member's
seat is not_found. Then preview the rows with
linkedin(operation="preview-sales-navigator", ...).

linkedin-sequences-restore-version

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/linkedin-sequence/versions/{versionId}/restore

Path: campaignId, versionId

Restore a campaign LinkedIn sequence to a saved version. Requires Campaigns edit access (owners, admins and editors by default).

POST /api/v1/campaigns/{campaignId}/linkedin-sequence/versions/{versionId}/restore.
Public. Sends Ken-Version 1.1. A campaign outside the workspace is not_found.

segment-linkedin-sequences-restore-version

Write. POST https://api.ken.so/v1/segments/{segmentId}/linkedin-sequence/versions/{versionId}/restore

Path: segmentId, versionId

Restore a segment LinkedIn sequence to a saved version. Requires Campaigns edit access (owners, admins and editors by default).

POST /api/v1/segments/{segmentId}/linkedin-sequence/versions/{versionId}/restore.
Public. Sends Ken-Version 1.1. A segment outside the workspace is not_found.

linkedin-sequences-save-version

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/linkedin-sequence/versions

Path: campaignId

Body (json): sourceVersionId integer, steps array

Save a campaign LinkedIn sequence version. Omit steps to snapshot the live sequence. Requires Campaigns edit access (owners, admins and editors by default).

POST /api/v1/campaigns/{campaignId}/linkedin-sequence/versions. Public. Sends Ken-Version 1.1.
With source_version_id, omitted or empty steps keep that version's steps.
A non-empty list overlays them. Steps take the LinkedIn sequence step fields,
the voice_note step's voice included; a voice the workspace cannot use is refused with 400.

segment-linkedin-sequences-save-version

Write. POST https://api.ken.so/v1/segments/{segmentId}/linkedin-sequence/versions

Path: segmentId

Body (json): sourceVersionId integer, steps array

Save a segment LinkedIn sequence version. Omit steps to snapshot the live sequence. Requires Campaigns edit access (owners, admins and editors by default).

POST /api/v1/segments/{segmentId}/linkedin-sequence/versions. Public. Sends Ken-Version 1.1.
With source_version_id, omitted or empty steps keep that version's steps.
A non-empty list overlays them. Steps take the LinkedIn sequence step fields,
the voice_note step's voice included; a voice the workspace cannot use is refused with 400.

update

Write. PATCH https://api.ken.so/v1/linkedin-accounts/{linkedinAccountId}

Path: linkedinAccountId

Body (json): dailyInviteCap integer, dailyMessageCap integer, dailyVisitCap integer, displayName string, handoffsMuted boolean, importConnections boolean, networkOnly boolean, paused boolean, ramp object, researchReads boolean, timezone string, workingHours string, workingHoursSchedule object

Update a LinkedIn account, or pause and resume it. Absent fields stay unchanged. Requires Delivery edit access (owners, admins and editors by default). Daily caps are clamped by the server.

PATCH /api/v1/linkedin-accounts/{linkedinAccountId}. Public. Sends Ken-Version 1.1.
Fields: display_name, timezone, working_hours_schedule, working_hours,
daily_invite_cap, daily_message_cap, daily_visit_cap, ramp, paused,
import_connections, network_only, handoffs_muted, research_reads.
timezone: an IANA id such as Europe/Bucharest; "" or null clears it (UTC).
working_hours_schedule: all seven days, e.g. {"mon": {"open": true,
"start": "09:00", "end": "17:00"}, ..., "sun": {"open": false}}; start and
end (HH:mm) are required on open days and at least one day is open.
Send it or working_hours (an object or its JSON string), not both; null (or
working_hours "") clears the seat to the default Mon-Fri 08:00-18:00. Every
other field is refused as null, since the API reads null as unchanged: omit
the field instead. Invalid values are
400 validation_failed naming the field (invalid_timezone, missing_day,
invalid_time, end_before_start, no_open_day, conflict).
ramp (object keyed by action, only while the account's rampPlansEnabled is
true, else 400 feature_off): per-action edits {"invite": {"start": 5,
"step_per_week": 5, "ceiling": 20}, ...}; the keys are invite, message,
visit, follow, reaction, comment, endorse or accept; absent numbers keep the
current value. The API clamps each value to the action's hard ceiling
(invite 20, message 50, visit 80, follow 20, reaction 30, comment 10,
endorse 15, accept 25, or lower by config). While rampPlansEnabled is true,
daily_invite_cap, daily_message_cap and daily_visit_cap also set the
invite, message and visit ceilings; a ramp entry wins.
Example: changes={"ramp": {"comment": {"step_per_week": 2}}}.
paused (boolean): true pauses outreach from the account (campaign invites, messages,
InMails, profile visits, withdrawals, approved Accounts notes) and sets pausedAt,
keeping the first pause time when it is already paused. false resumes it and clears
pausedAt; the waiting actions continue where they stopped. Paused actions are never
failed or moved to email. The autonomous reply agent's sends wait too. A person's
replies from the Inbox and inbox sync keep running.
Example: changes={"paused": true}.
import_connections (boolean, DEV-5778): true imports the seat's connections into Accounts,
kept out of All and of every automated pass until someone works them (ICP fits show in
All); false stops new imports. Only the seat's connector or an admin (403 otherwise), with
the linkedin_connections_import flag on (400 feature_off otherwise).
Example: changes={"import_connections": true}.
network_only (boolean, DEV-8542): true keeps syncing the seat but takes it out of every
campaign (listed in removedFromCampaignIds), switches its inbound requests off and never
sends from it on its own; false makes it a full seat, in no campaign. Connector or admin
only (403); true needs warm_paths_v2 (400 feature_off). false on a Network member's
seat is 403 network_member (DEV-8704).
handoffs_muted (boolean, DEV-8752): true mutes warm path handoffs, so no teammate's
warm path hands the seat's owner a hop through any of their seats (their start is
refused with guardrail_handoff_muted); the account then has handoffsMutedAt. false
unmutes this account.
Connector or admin only (403); true needs warm_paths_v2 (400 feature_off).
research_reads (boolean, DEV-9945): true lets Kenso read public LinkedIn posts on the
account a few times a day, inside its working hours; the account then has
researchReadsEnabledAt (the first time it was turned on). false turns that off. Only the
member who connected the account may send true (403 otherwise, admins included); that
member or an admin may send false.
Example: changes={"research_reads": true}.