Kenso MCP tools

Markets markets

Kenso's market packs: how to write cold email in each language and country (formality, salutations, sign-offs, style, banned phrases) and each country's cold email rules, a campaign's steps written in each language it enables, and the consent-first countries a campaign must acknowledge before launch. Not stock or financial markets.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through markets_read and changes through markets_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: compliance-acknowledge, localizations-approve, localizations-generate, compliance-get, languages-get, get, billing-plans-list, localizations-list, list, localizations-regenerate, localizations-update

compliance-acknowledge

Write. Early access: needs multilingual_outreach on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/compliance/acknowledgements

Path: campaignId

Body (json): countries array

Acknowledge the cold email rules of a campaign's consent-first countries, so launch can proceed.

POST /api/v1/campaigns/{campaignId}/compliance/acknowledgements with {"countries": ["ES"]}. Needs the
multilingual_outreach flag (404 while it is off) and campaign edit. Sends Ken-Version 1.1.

countries: ISO-2 codes of countries markets(operation="compliance-get") lists for the campaign. Records the
caller and the time for each, which lets campaigns(operation="launch") proceed for that country. Acknowledge only
after the user has read each country's note and agreed: the acknowledgement is theirs, and it goes on the
workspace's audit log. A country already acknowledged keeps its first acknowledgement, so a repeat is harmless.
Returns the same shape as compliance-get.

Errors (400 validation_failed, details[].code, field countries[i]): required (no country), unknown_country (not
an ISO-2 code Kenso knows), not_required (the campaign has no contacts there, or its rules need no
acknowledgement). Any error records nothing. A campaign in another workspace is 404.

Examples:
- markets(operation="compliance-acknowledge", campaign_id=812, countries=["ES"], client_id=7)
- markets(operation="compliance-acknowledge", campaign_id=812, countries=["ES", "DE"], client_id=7)

localizations-approve

Write. Early access: needs multilingual_outreach on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/localizations/{localizationId}/approve

Path: campaignId, localizationId

Query: channel string

Approve one localized step of a campaign for sending; returns the localization.

POST /api/v1/campaigns/{campaignId}/localizations/{localizationId}/approve. Needs the multilingual_outreach flag
(404 while it is off) and campaign edit. Sends Ken-Version 1.1.

localization_id is the id from markets(operation="localizations-list"). channel (email or linkedin) is needed
only when an email and a LinkedIn localization of the campaign share that id (400 channel_required otherwise).
Only a current draft that passed its quality check is approved: qaReport.passed is true and qaScore reached the
market pack's threshold (a localization a person edited is approved on the rules alone). Records the caller as
approvedByUserId (none for an API key with no user) and approvedAt.

Errors: 409 localization_not_approvable with details[].code not_draft, stale (written from older step text or an
older market pack: run localizations-generate or localizations-regenerate), qa_failed or score_below_threshold;
409 localization_generating while the localization job has it queued; 404 for an id the campaign does not have.

Examples:
- markets(operation="localizations-approve", campaign_id=812, localization_id=5003, client_id=7)
- markets(operation="localizations-approve", campaign_id=812, localization_id=12, channel="linkedin", client_id=7)

localizations-generate

Write. Early access: needs multilingual_outreach on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/localizations

Path: campaignId

Body (json): channel string, languages array, stepIds array

Queue the writing of a campaign's steps in the languages it enables; returns every localization of the campaign.

POST /api/v1/campaigns/{campaignId}/localizations with {"languages": [...], "stepIds": [...], "channel": ...}. Needs the
multilingual_outreach flag (404 while it is off) and campaign edit. Sends Ken-Version 1.1. Answers 202.

languages, step_ids and channel are optional: absent or empty means every language the campaign enables (its
enabledLanguages) and every active email or LinkedIn step with text (not a Studio step, not an AI connection
note). channel (email or linkedin) keeps one channel's steps; an email and a LinkedIn step can share an id, and
channel picks one. A missing localization is created as a draft; a stale, failed or needs_review one, and one written from
older step text or an older market pack, is queued again. A current draft or approved localization, and one
already queued, stay as they are. A localization a person edited (editedByHuman) is queued again only when
step_ids names its step. Nothing is written here: the localization job writes the queued rows
(generating true until it does), so call markets(operation="localizations-list") later to read them.

Errors (400 validation_failed, details[].code): language_not_enabled (the campaign does not enable that
language), no_enabled_languages (the campaign enables none: set enabledLanguages first),
unsupported_language (no market pack for it), step_not_localizable (not an active step of the campaign with
text), invalid_value on field channel. A campaign in another workspace is 404. While the localization job is not on for the workspace,
nothing is queued: 409 invalid_state with details[].code localization_disabled.

Examples:
- markets(operation="localizations-generate", campaign_id=812, client_id=7)
- markets(operation="localizations-generate", campaign_id=812, languages=["fr-FR"], step_ids=[11, 12], client_id=7)
- markets(operation="localizations-generate", campaign_id=812, step_ids=[11], channel="linkedin", client_id=7)

compliance-get

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

Path: campaignId

Read a campaign's consent-first countries: each country's cold email rule, contact count and acknowledgement.

GET /api/v1/campaigns/{campaignId}/compliance. Needs the multilingual_outreach flag (404 while it is off) and
campaign view. Sends Ken-Version 1.1.

Returns data {acknowledgementRequired, countries[]}. countries lists each country the campaign's live contacts sit
in whose cold email rules launch asks someone to acknowledge (Spain, Germany, ...), most contacts first: iso2 (ES),
name, regime (opt_out, consent or unresolved), note (a short summary of the rule; not legal advice), sources
(public pages), contactCount, and acknowledgedAt and acknowledgedByUserId once someone acknowledged it (absent
before). acknowledgementRequired is true while any listed country has no acknowledgement: launch then answers
409 acknowledgement_required, and launch readiness lists acknowledgement_required. Show the user each note, then
record their agreement with markets(operation="compliance-acknowledge"). A campaign in another workspace is 404.

Examples:
- markets(operation="compliance-get", campaign_id=812, client_id=7)

languages-get

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

Path: campaignId

Read a campaign's languages: its language settings, the market packs it can enable and its contacts per language.

GET /api/v1/campaigns/{campaignId}/languages. Needs the multilingual_outreach flag (404 while it is off) and
campaign view. Sends Ken-Version 1.1.

Returns data {sourceLanguage, languageMode, enabledLanguages, formalityOverrides, languageFallback, available,
mix, unresolved}:
- sourceLanguage (en, or a locale such as fr-FR), languageMode (source_only or auto), enabledLanguages (locales
  such as fr-FR), formalityOverrides (locale to formal or informal), languageFallback (source or hold): the
  campaign's settings, as campaigns(operation="get") returns them; change them with campaigns(operation="update").
- available: every market pack the campaign can enable, by locale: {locale, name (in its own language), status}
  with status supported or tested. Draft packs are left out.
- mix: the campaign's contacts that can still be contacted (live, not do-not-contact) per outreach language, most
  contacts first: {locale, contacts, lowConfidence}. lowConfidence of a locale's contacts are under the routing
  confidence floor and get the source language.
- unresolved: contacts with no outreach language yet.
A campaign in another workspace is 404.

Examples:
- markets(operation="languages-get", campaign_id=812, client_id=7)

get

Read. GET https://api.ken.so/v1/markets/{locale}

Path: locale

Get one market pack with the cold email notes of its countries. Returns { pack, countries, status }. An unknown locale returns a not-found error.

locale is a pack locale such as fr-FR or es-ES, any case (FR-fr reads as fr-FR).
markets(operation="list") lists the locales there are.

pack is markets/<locale>.json as written: language, formality, salutations,
signOffs, style, bannedPhrases, spamPhrases, examples and the rest.
countries are the countries whose official language this pack writes, each as
markets/countries.json has it: iso2, name, languages (code, locale, share,
official) and coldEmail (regime opt_out, consent or unresolved, note, sources,
requiresAcknowledgement). Every note ends with "Not legal advice."
status is "tested" (passed the quality check) or "supported". A draft pack is
not served: its locale returns the not-found error, and so does a bare language
such as fr.

GET /api/v1/markets/{locale}. Public. Sends Ken-Version 1.1.

billing-plans-list

Read. GET https://api.ken.so/v1/billing/plans

List the plans a new workspace can pick: free, platform, performance.

GET /api/v1/billing/plans. Sends Ken-Version 1.1. Static, so it needs no
workspace (X-Ken-Workspace-Id is sent only when one is given or pinned).
Returns creditUsdCents (one credit in US cents), freeSignupCredits and
plans, in the order free, platform, performance. Each plan has id, name,
tagline, includes (bullet copy), canSend (false for free: a new Free
workspace cannot send until it picks a plan) and salesLed (true for
performance). Platform adds includedCredits, includedCreditsUsdCents and
prices (monthly, plus quarterly and annual when configured; each has
usdCents, currency, interval and perMonthUsdCents), read from Stripe and
left out when Stripe cannot be read. Performance adds bookingUrl. To buy
Platform, start a checkout with billing(operation="checkout-sessions-create").

localizations-list

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

Path: campaignId

Query: channel string, language string, stepId integer

List a campaign's steps in each language: the localized text, its English mirror, score and status.

GET /api/v1/campaigns/{campaignId}/localizations. Needs the multilingual_outreach flag (404 while it is off)
and campaign view. Sends Ken-Version 1.1.

One item per live email or LinkedIn step and language, email first, then by step order, variant and language:
id, channel (email or linkedin), stepId, stepOrder, variant (a to d), language (fr-FR), subjectLine (email only),
bodyContent, status, generating, sourceHash, stale, packVersion, mirrorLanguage (en), mirrorSubject, mirrorBody,
qaScore (0 to 100), qaReport {passed, errors[{code, message}]} (a judge finding has code judge), editedByHuman,
approvedByUserId, approvedAt, lastError, modifiedAt.
status is draft, approved, stale, needs_review or failed. stale is true when the row is marked stale, or was
written from older step text or an older market pack: run localizations-generate again. generating is true while
the localization job has the row queued. One page: pagination.hasMore is always false.

language keeps one locale (any casing). step_id keeps the rows of the email or LinkedIn step with that id.
channel (email or linkedin) keeps one channel's rows; an email and a LinkedIn step can share an id, and channel
picks one. A campaign in another workspace is 404.

Examples:
- markets(operation="localizations-list", campaign_id=812, client_id=7)
- markets(operation="localizations-list", campaign_id=812, language="fr-FR", client_id=7)

list

Read. GET https://api.ken.so/v1/markets

Query: cursor string, limit integer

List every market pack: locale, language, status and countries. Returns { markets: [{ locale, language, status, countries: [iso2] }] }, sorted by locale.

status is "tested" (passed the quality check) or "supported"; draft packs are
not listed.
countries are the ISO-2 codes of the countries one of whose official languages
this pack writes: the pack of that exact locale, else the language's primary
pack (Belgium's French reads fr-FR until an fr-BE pack exists).
markets(operation="get", locale=...) returns one pack with each country's
cold email notes.

GET /api/v1/markets. Public. Sends Ken-Version 1.1. The tool follows the cursor
and returns every market at once.

localizations-regenerate

Write. Early access: needs multilingual_outreach on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/localizations/{localizationId}/regenerate

Path: campaignId, localizationId

Query: channel string

Body (json): instruction string

Queue one localized step to be written again, with an optional instruction; returns the localization.

POST /api/v1/campaigns/{campaignId}/localizations/{localizationId}/regenerate with {"instruction": ...}. Needs the
multilingual_outreach flag (404 while it is off) and campaign edit. Sends Ken-Version 1.1. Answers 202.

instruction (optional, up to 2,000 characters) says what to change, such as "Shorter, and less formal."; the
localization job rewrites the current text with it, or writes it anew without one. The localization becomes a
draft (an approval is withdrawn, so a live campaign stops sending it: its contacts are held or get the source
text, as the campaign's language fallback says, until it is approved again), and generating is true until the job
has written it: call
markets(operation="localizations-list") later to read it. This rewrites text a person edited. channel as for
localizations-approve.

Errors: 409 localization_generating while the job has it queued; 400 validation_failed with details[].code
language_not_enabled (the campaign no longer enables that language), step_not_localizable (the step has no text to
localize) or too_long (instruction); 409 invalid_state with details[].code localization_disabled while the
localization job is not on for the workspace; 404 for an id the campaign does not have.

Examples:
- markets(operation="localizations-regenerate", campaign_id=812, localization_id=5003, instruction="Shorter.", client_id=7)

localizations-update

Write. Early access: needs multilingual_outreach on for the workspace. PATCH https://api.ken.so/v1/campaigns/{campaignId}/localizations/{localizationId}

Path: campaignId, localizationId

Query: channel string

Body (json): bodyContent string, subjectLine string

Replace the text of one localized step with your own; returns the localization with its rule check.

PATCH /api/v1/campaigns/{campaignId}/localizations/{localizationId} with {"subjectLine": ..., "bodyContent": ...}.
Needs the multilingual_outreach flag (404 while it is off) and campaign edit. Sends Ken-Version 1.1.

Send subject_line, body_content or both; an absent one keeps the stored text, and a LinkedIn localization has no
subject. The text is stored as sent (the unsubscribe link text is set to the market pack's) and checked by the
rules with no model call: qaReport holds their result. editedByHuman becomes true and the localization a draft
(an approval is withdrawn, so a live campaign stops sending it until it is approved again, as for
localizations-regenerate); mirrorSubject, mirrorBody and qaScore stay as they were, for the text before the
edit. An edited draft whose rules pass can be approved with markets(operation="localizations-approve").
channel as for localizations-approve.

Errors: 400 validation_failed for a blank body, a blank subject for a step that has one, or a subject on a
LinkedIn localization, and, while campaign images are on for the workspace, for an email text with image tokens
a sequence save would refuse (more than two, one in the subject or in a handwritten letter, or one not on its own
line or in its own paragraph; the message is the sequence save's, nothing is stored); 409 localization_generating
while the localization job has it queued; 404 for an id the campaign does not have.

Examples:
- markets(operation="localizations-update", campaign_id=812, localization_id=5003, body_content="<p>Bonjour {firstName},</p>...", client_id=7)