Kenso MCP tools

Lists lists

Contact lists: a campaign's contact import lists (list_id; CSV, Kenso Search or campaign imports), plus the blocklist and a campaign's custom variables. Not people lists: saved lists of people or companies are the saved_lists tool, with their own ids, and delete here never takes a saved_list_id.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through lists_read and changes through lists_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: bulk-create, blocklist-entries-create, blocklist-rules-create, custom-variables-create, blocklist-entries-delete, blocklist-rules-delete, custom-variables-delete, delete, get, import, blocklist-entries-list, blocklist-rules-list, custom-variables-list, list, blocklist-rules-preview, blocklist-entries-update, blocklist-rules-update, custom-variables-update

bulk-create

Write. POST https://api.ken.so/v1/blocklist-entries/bulk-create

Body (json): entries array, reason string, type string, values array

Add up to 1,000 blocklist values of one type. Per-value outcomes are succeeded or failed. Duplicates stay failed with already_exists and keep their own reason.

POST /api/v1/blocklist-entries/bulk-create. Public. Sends Ken-Version 1.1.
Requires the `workspace_settings` permission. entry_type is email or domain.
Pass values (a list of emails or domains) or entries (a list of
{"value": "...", "reason": "..."} for a reason per value), not both.
reason (at most 200 characters) applies to every value without its own.
A domain a customer account or a blocklist rule already lists becomes a
manual entry under its id and is in succeeded with claimed: true. A shared
mail provider domain (gmail.com) fails with code shared_mail_provider;
another malformed value with invalid. To undo, pass the succeeded ids
without claimed: true to segments(operation="blocklist-entries-bulk-delete").
A claimed entry was blocked before this add, so deleting it would unblock
that domain.

blocklist-entries-create

Write. POST https://api.ken.so/v1/blocklist-entries

Body (json): reason string, type string, value string

Add one email or domain to the blocklist. A duplicate entry is validation_failed and keeps its own reason. Returns 201.

POST /api/v1/blocklist-entries. Public. Sends Ken-Version 1.1.
Requires the `workspace_settings` permission. entry_type is email or domain.
reason is optional free text (at most 200 characters) saying why the value
is blocked, such as "Competitor" or "Current client".
A domain a customer account or a blocklist rule already lists becomes a
manual entry under its id, with this reason, and returns claimed: true.
A shared mail provider domain (gmail.com, hotmail.co.uk, web.de) is
validation_failed with detail code shared_mail_provider: block those
addresses one by one instead.

blocklist-rules-create

Write. POST https://api.ken.so/v1/blocklist-rules

Body (json): accountStages array, accountTypes array, crmLifecycles array, crmListId string, enabled boolean, name string, reason string, releaseAfterDays integer, stages array

Create a blocklist rule; an enabled rule blocks its domains and people right away. A workspace has at most 20 rules (the 21st is conflict). Returns 201.

POST /api/v1/blocklist-rules. Public. Sends Ken-Version 1.1. Needs the
blocklist_rules feature. Requires workspace settings access.

name 1-100 characters. Send at least one of stages, account_stages, account_types,
crm_lifecycles and crm_list_id: stages up to 20 keys from
opportunities(operation="stages-list"), none archived; account_stages the account
stages to block, up to 16 of warming, engaged, meeting_booked, in_deal, onboarding,
client, churned, nurture, paused, lost, network, not_a_fit, competitor, do_not_contact
(never new or researching, where every new account starts); account_types any of
client, lost, churned, partner, competitor, investor, do_not_contact (never prospect),
kept for older callers (use account_stages); crm_lifecycles up to 5 of lead, prospect, opportunity,
customer, churned (HubSpot, Salesforce), holding at most 10,000 CRM records; crm_list_id
a contact or company list of the connected CRM, at most 10,000 members. CRM criteria bind the workspace's connected CRM
(crmConnectionId) and fail as on the preview. The rule matches an account with a live
opportunity in one of its stages, in one of its account stages or whose type is one of
its account types, and the
CRM records in its lifecycle stages or on its list: a company blocks its domain, a
contact its company domain (or its email with only a free email domain), a contact
list its people's emails. reason 1-200 characters, written on every blocklist entry the
rule adds. enabled defaults to true. release_after_days (1-3650, default none: never
releases) lets an account matched by stage come off that many days after its deal in
the stages closed; a deal with no close date and a match by account stage, by type or
from the CRM never release. The rule goes last and its list is read right away. A domain or email any
blocklist entry already lists keeps that entry; a manual, own-domain or customer entry
is never changed. Preview first with lists(operation="blocklist-rules-preview").

custom-variables-create

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/custom-variables

Path: campaignId

Body (json): isRequiredForSending boolean, name string, useAsAiContext boolean, variableKey string

Declare one custom variable. An existing key is updated. Returns 201 and Location. Requires Campaigns edit.

POST /api/v1/campaigns/{campaignId}/custom-variables. Public. Sends Ken-Version 1.1.
The API normalizes variable_key. use_as_ai_context and is_required_for_sending
are optional booleans.

blocklist-entries-delete

Write. DELETE https://api.ken.so/v1/blocklist-entries/{entryId}

Path: entryId

Remove one blocklist entry. An entry outside the workspace is not_found. Returns 204.

DELETE /api/v1/blocklist-entries/{entryId}. Public. Sends Ken-Version 1.1.
Requires the `workspace_settings` permission.

blocklist-rules-delete

Write. DELETE https://api.ken.so/v1/blocklist-rules/{ruleId}

Path: ruleId

Delete a blocklist rule. Entries only it matched come off the blocklist. Returns 204. A rule of another workspace is not_found.

DELETE /api/v1/blocklist-rules/{ruleId}. Public. Sends Ken-Version 1.1. Needs the
blocklist_rules feature. Requires workspace settings access. Soft delete; the rest
renumber.

custom-variables-delete

Write. DELETE https://api.ken.so/v1/campaigns/{campaignId}/custom-variables/{variableKey}

Path: campaignId, variableKey

Remove one custom variable. Returns 204. Requires Campaigns edit.

DELETE /api/v1/campaigns/{campaignId}/custom-variables/{variableKey}.
Public. Sends Ken-Version 1.1.

delete

Write. DELETE https://api.ken.so/v1/lists/{listId}

Path: listId

Soft-delete a campaign import list that no contact references. Not a saved (people or company) list. Public. Requires Campaigns edit. A list that still has contacts is validation_failed. A saved list id is refused: delete those with saved_lists(operation="delete").

DELETE /api/v1/lists/{listId}. Public. Sends Ken-Version 1.1.
Requires Campaigns edit. A list outside the workspace is not_found before
the delete. A list that still has contacts, including soft-deleted
contacts, is validation_failed. The response is the deleted list.
Campaign lists and saved lists number their ids separately, so the id is
checked first: one that is only a saved list of this workspace is refused,
naming it, and nothing is deleted. One that is both a campaign list and a
saved list of this workspace is refused unless confirm_campaign_list is
true (DEV-8724).

get

Read. GET https://api.ken.so/v1/lists/{listId}

Path: listId

Return one campaign list. Public. A list outside the workspace is not_found.

GET /api/v1/lists/{listId}. Public. Sends Ken-Version 1.1.
Requires Campaigns view. A list outside the workspace is not_found.
listType and status are lowercase snake_case. sourceCampaignId is omitted
when null.

import

Write. POST https://api.ken.so/v1/blocklist-entries/imports

Import blocklist rows from CSV text. The CSV has email and/or domain columns and an optional reason column. Requires the `workspace_settings` permission.

POST /api/v1/blocklist-entries/imports. Public. Sends Ken-Version 1.1.
Multipart field file is a .csv. Blank files are rejected.

csv_content is the CSV text: read the file yourself and pass its text.
The hosted MCP refuses file_path, because it cannot read your machine.
Off the hosted MCP, file_path opens only a .csv inside the MCP export
directory. With csv_content, file_path only names the upload.

reason (at most 200 characters) applies to every row without its own
reason column value. Rows already on the blocklist keep their reason.

blocklist-entries-list

Read. GET https://api.ken.so/v1/blocklist-entries

Query: cursor string, hasReason boolean, includeCounts boolean, includeTotal boolean, limit integer, q string, sort string, source string, type string, value string

List blocklist entries in the current workspace. Oldest first by default; sort="-createdAt" lists newest first. q searches the value and the reason. Filter by entry_type, source or has_reason.

GET /api/v1/blocklist-entries. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Each entry has id, type, value,
createdAt, source (manual, own_domain, customer or rule) and reason (why it
is blocked; omitted when there is none).

Filters, all optional: entry_type (email or domain), value (an exact match),
q (a case-insensitive substring of the value or the reason), source (a list
of manual, own_domain, customer, rule), has_reason (true or false).
sort is createdAt (oldest first, the default) or -createdAt (newest first);
keep the same sort while paging with cursor.
include_total=true adds pagination.total, every entry the filters match.
include_counts=true adds counts {all, emails, domains, fromCrm, noReason}
for the whole workspace, whatever the filters.

blocklist-rules-list

Read. GET https://api.ken.so/v1/blocklist-rules

List the workspace's blocklist rules in position order. Each rule has matches: the accounts and CRM records it matches now and the domains and people it blocks.

GET /api/v1/blocklist-rules. Public. Sends Ken-Version 1.1. Needs the
blocklist_rules feature. Open to any workspace member.

A rule: id, name, stages (opportunity stage keys), accountStages (account stages it
matches), accountTypes (account types it matches, kept for older callers),
crmLifecycles (CRM lifecycle stages), crmList {externalId, name, objectType
(contact or company), members and readAt of its last read (absent before the first)}
(absent without a list), crmConnectionId (absent without CRM criteria), reason,
enabled, position (0-based), releaseAfterDays (absent: never releases), matches
{accounts, domains, people (emails it blocks), crmRecords}, createdAt, updatedAt. It
matches an account with a live opportunity in one of its stages, in one of its
accountStages or whose type is one of its accountTypes (counted once), and the
connected CRM's records in its lifecycle
stages or on its list. A CRM company blocks its domain; a CRM contact blocks its
company domain, or its email when it has only a free email domain; a contact list
blocks its people's emails. Kenso reads the list again about every 15 minutes, so a
person who leaves it comes off. With releaseAfterDays a stage match holds only while
one of the account's deals in the stages closed less than that many days ago (or has
no close date); an account stage, type or CRM match never releases. The first enabled rule that
matches a domain or email gives its blocklist entry the reason. Entries a rule adds
show source rule on lists(operation="blocklist-entries-list").

custom-variables-list

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/custom-variables

Path: campaignId

Query: cursor string, limit integer, q string

List a campaign's custom variables. Ordered by key. q matches the key or the name.

GET /api/v1/campaigns/{campaignId}/custom-variables. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.

list

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/lists

Path: campaignId

Query: cursor string, limit integer

List a campaign's import lists, newest first. Public. There is no totalCount.

GET /api/v1/campaigns/{campaignId}/lists. Public. Sends Ken-Version 1.1.
Requires Campaigns view. Newest first. limit is 1 to 200. Omit it for the
server default. There is no totalCount.
listType is lowercase snake_case: csv, ken_search, or campaign_import.
status is lowercase snake_case: to_scrape, in_progress, scraped, error,
done, or draft. sourceCampaignId is omitted when null.
A campaign outside the workspace is not_found before the list is read.

blocklist-rules-preview

Read. GET https://api.ken.so/v1/blocklist-rules/preview

Query: accountStages string, accountTypes string, crmLifecycles string, crmListId string, releaseAfterDays integer, stages string

Preview what a blocklist rule with these stages, account stages or CRM criteria would block. Never writes. Returns accounts, domains, people, crmRecords, alreadyBlocked, samples and skipped counts.

GET /api/v1/blocklist-rules/preview?stages=won,churned&accountStages=competitor. Public.
Sends Ken-Version 1.1. Needs the blocklist_rules feature. Requires Accounts view, since
it names accounts.

Send at least one of stages, account_stages, account_types, crm_lifecycles and
crm_list_id. stages: up to 20 keys from opportunities(operation="stages-list"); an
unknown or archived key is validation_failed. account_stages: the account stages to
block, up to 16 of warming, engaged, meeting_booked, in_deal, onboarding, client,
churned, nurture, paused, lost, network, not_a_fit, competitor, do_not_contact (never
new or researching, where every new account starts). account_types: client, lost,
churned, partner, competitor, investor or do_not_contact (never prospect); kept for
older callers, use account_stages. crm_lifecycles: up to 5 of lead, prospect,
opportunity, customer, churned (never other), holding at most 10,000 CRM records;
needs a CRM that maps lifecycle stages (HubSpot, Salesforce). crm_list_id: a contact or
company list of the connected CRM (crm_connections lists), at most 10,000 members, read
live now and never stored; needs a CRM Kenso reads lists from. CRM criteria fail with
not_enabled (blocklist_rules_crm off), invalid_state (no connected CRM), unsupported,
out_of_range (unknown or too large list, or too many records in the stages), or the
CRM's own 503 or 429. Response: accounts (with a live opportunity in one
of the stages, in one of the account stages or of one of the types, each once),
domains (distinct domains a rule
would block), people (distinct emails it would block), crmRecords (CRM records
matched), alreadyBlocked (of the domains and people, how many a blocklist entry of any
source lists), sample [{accountId, name, domain}], crmSample [{externalId, name, value}]
(up to 10 CRM records with the email or domain each blocks), skipped {noDomain
(accounts and CRM companies with no domain), noEmail (CRM contacts with neither a
company domain nor an email), freeMail (free email domains, never blocked as a
domain), released (accounts the release window already let go)}. release_after_days
(1-3650) previews a release window: an account matched by stage counts only while one
of its deals in the stages closed less than that many days ago or has no close date; a
match by account stage, by type or from the CRM never releases.

blocklist-entries-update

Write. PATCH https://api.ken.so/v1/blocklist-entries/{entryId}

Path: entryId

Body (json): reason string

Set or clear why a blocklist entry is blocked. An empty reason clears it. An entry outside the workspace is not_found.

PATCH /api/v1/blocklist-entries/{entryId}. Public. Sends Ken-Version 1.1.
Requires the `workspace_settings` permission. reason is free text, at most 200 characters, such as
"Competitor" or "Current client". Returns the updated entry.

blocklist-rules-update

Write. PATCH https://api.ken.so/v1/blocklist-rules/{ruleId}

Path: ruleId

Body (json): accountStages array, accountTypes array, crmLifecycles array, crmListId string, enabled boolean, name string, position integer, reason string, releaseAfterDays integer, stages array

Update a blocklist rule. Fields left out stay; the blocklist follows right away. Entries no enabled rule matches any more come off. A rule of another workspace is not_found.

PATCH /api/v1/blocklist-rules/{ruleId}. Public. Sends Ken-Version 1.1. Needs the
blocklist_rules feature. Requires workspace settings access.

Send at least one of name (1-100), stages (up to 20 live stage keys), account_stages
(the account stages to block, with the values of create), account_types (client, lost,
churned, partner, competitor, investor, do_not_contact; kept for older callers),
reason (1-200),
enabled, position (0-based; past the last rule moves it last, the rest renumber),
release_after_days (1-3650: an account matched by stage comes off that many days after
its deal in the stages closed), clear_release_after_days (sends null: the rule never
releases), crm_lifecycles (up to 5 of lead, prospect, opportunity, customer, churned),
crm_list_id (a contact or company list of the connected CRM; read right away) or
clear_crm_list (sends null: drops the list). Setting a CRM criterion binds the
connected CRM and fails as on create; a kept list or kept lifecycle stages must be
on the connected CRM's account (invalid_state on crmListId or crmLifecycles
otherwise: send crm_list_id or clear_crm_list, and crm_lifecycles again or []);
clearing both CRM criteria clears crmConnectionId. stages, account_stages, account_types or crm_lifecycles may be []
while the rule keeps another criterion; a rule with none is validation_failed. Entries whose first matching
rule changed take its reason.

custom-variables-update

Write. PATCH https://api.ken.so/v1/campaigns/{campaignId}/custom-variables/{variableKey}

Path: campaignId, variableKey

Body (json): isRequiredForSending boolean, name string, useAsAiContext boolean

Update one custom variable. Absent fields stay unchanged. Requires Campaigns edit.

PATCH /api/v1/campaigns/{campaignId}/custom-variables/{variableKey}.
Public. Sends Ken-Version 1.1. The API normalizes variable_key.