Kenso MCP tools

Calling calling

The built-in dialer's setup: calling settings, US and Canadian numbers bought for credits, what a call costs and the monthly calling spend limit. Calls themselves are placed in the Kenso app. Also outside dialers (Aircall, Ringover, a signed dialer webhook) and their members (dialer-*).

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through calling_read and changes through calling_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: dialer-connections-aircall-authorize-url, dialer-connections-aircall-connect, dialer-webhook-connect, dialer-connections-delete, dialer-connections-get, dialer-connections-members-list, dialer-connections-members-update, numbers-available, numbers-buy, numbers-list, numbers-release, numbers-update, rates-get, dialer-connections-ringover-connect, settings-get, settings-update, spend-limit-get, spend-limit-update, voicemails-delete, voicemails-list

dialer-connections-aircall-authorize-url

Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/integrations/aircall/connection/authorize-url

Get Aircall's consent URL to connect the workspace through Kenso's Aircall app.

POST /api/v1/integrations/aircall/connection/authorize-url. Staff, or a workspace with the calls
flag (workspace admin). Sends Ken-Version 1.1. Returns url, valid for 10 minutes. A person opens it
while signed in to Kenso: an Aircall admin approves, and Settings > Calling in the Kenso app finishes
the connect in that person's session (an agent cannot finish it). invalid_state with detail
not_configured while Kenso's Aircall app is not set up (use dialer-connections-aircall-connect with
an API ID and token instead); conflict when Aircall is already connected.

dialer-connections-aircall-connect

Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/integrations/aircall/connection

Body (json): apiId string, apiToken string

Connect the workspace's Aircall account with its API ID and API token.

POST /api/v1/integrations/aircall/connection. Staff, or a workspace with the calls flag (workspace
admin). Sends Ken-Version 1.1. api_id and api_token come from Aircall (Integrations > API Keys).
Kenso checks them with Aircall, adds its webhook to the Aircall account so every call comes back to
Kenso, then stores both encrypted; they are never returned. Returns 201 with the connection as
dialer-connections-get returns it (connectedAs is the Aircall company). Aircall refusing the
credentials is validation_failed on apiToken; Aircall already connected, or Aircall refusing Kenso's
webhook (an account holds 100 at most), is conflict; Aircall not answering is unavailable. Nothing
is stored on any of them. Then link the Aircall users to members with dialer-connections-members-list
and dialer-connections-members-update.

dialer-webhook-connect

Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/integrations/dialer-webhook/connection

Create the workspace's dialer webhook: a URL and signing secret any dialer posts calls to.

POST /api/v1/integrations/dialer-webhook/connection. Staff, or a workspace with the calls flag
(workspace admin). Sends Ken-Version 1.1. Returns 201 with connection, url, hookKey and secret.
hookKey and secret are shown only in this response: Kenso keeps a hash and an encrypted copy. The
dialer posts each call to url with X-Ken-Signature: t=<unix seconds>,v1=<hex>, the hex being
HMAC-SHA256(secret, t + "." + body); the body and the answers are in the Kenso API docs
(dialer-webhook.md). A workspace with a dialer webhook already connected is conflict: disconnect it
with dialer-connections-delete first.

dialer-connections-delete

Write. Early access: needs calls on for the workspace. DELETE https://api.ken.so/v1/integrations/{integrationKey}/connection

Path: integrationKey

Disconnect a dialer. Its calls stop reaching Kenso; calls already logged stay.

DELETE /api/v1/integrations/{integrationKey}/connection. Staff, or a workspace with the calls flag
(workspace admin). Sends Ken-Version 1.1. integration_key: aircall, ringover, dialpad, justcall,
cloudtalk or dialer-webhook. Kenso asks the dialer to stop sending, then clears the tokens or the webhook secret. Returns 204.
Not connected is not found. A dialer webhook that is reconnected gets a new URL and secret.

dialer-connections-get

Read. Early access: needs calls on for the workspace. GET https://api.ken.so/v1/integrations/{integrationKey}/connection

Path: integrationKey

Return the workspace's connection to a dialer.

GET /api/v1/integrations/{integrationKey}/connection. Staff, or a workspace with the calls flag
(workspace admin). Sends Ken-Version 1.1. integration_key: aircall, ringover, dialpad, justcall,
cloudtalk or dialer-webhook. Returns provider, status (connected or needs_reconnect), connectedAs, connectedAt and lastEventAt
(omitted until the dialer sent an event). Tokens and secrets are never returned. Not connected is not found.

dialer-connections-members-list

Read. Early access: needs calls on for the workspace. GET https://api.ken.so/v1/integrations/{integrationKey}/connection/members

Path: integrationKey

List the dialer's users and the Kenso member each one is.

GET /api/v1/integrations/{integrationKey}/connection/members. Staff, or a workspace with the calls
flag (workspace admin). Sends Ken-Version 1.1. integration_key: aircall, ringover, dialpad, justcall or
cloudtalk (a dialer webhook has no user directory: provider_not_available). Up to 500 users: externalUserId, email, name, numbers
(E.164), memberId and match (linked: saved; email: the member with the user's email, saved by
dialer-connections-members-update). Unavailable while the dialer cannot be reached.

dialer-connections-members-update

Write. Early access: needs calls on for the workspace. PUT https://api.ken.so/v1/integrations/{integrationKey}/connection/members

Path: integrationKey

Body (json): members array

Replace which Kenso member each dialer user is.

PUT /api/v1/integrations/{integrationKey}/connection/members. Staff, or a workspace with the calls
flag (workspace admin). Sends Ken-Version 1.1. integration_key: aircall, ringover, dialpad, justcall or cloudtalk. members: every
link to keep, [{"member_id": 31, "external_user_id": "1234"}], up to 500; a member or a user once
each. A member left out is unlinked; an empty list unlinks everyone. external_user_id comes from
dialer-connections-members-list. Returns the members list as that operation does.

numbers-available

Read. Early access: needs calling on for the workspace. GET https://api.ken.so/v1/calling/numbers/available

Query: areaCode string, country string, locality string

Search up to 10 local phone numbers for sale in the US or Canada, by area code or city. Requires the workspace_settings permission.

GET /api/v1/calling/numbers/available. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
country: US or CA (and one the workspace calls). area_code: three digits. locality: a city.
Returns data [{e164, countryIso2, locality, region, monthlyCredits}]. 503 provider_unavailable
when the carrier is not set up or not reachable.

numbers-buy

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

Body (json): areaCode string, assignedMemberId integer, cnam string, country string, e164 string, locality string

Buy a local phone number for 100 credits a month. Only when the user asks to buy one. Requires the workspace_settings and billing permissions.

POST /api/v1/calling/numbers. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
country: US or CA. e164: a number from calling(operation="numbers-available"); when a fresh
search no longer offers it, the first number that search offers is bought instead, so tell
the user the number you got. area_code (three digits) and locality narrow that search; a
US or Canadian e164 sent without area_code is searched for in its own area code.
assigned_member_id: an active member with no number yet. cnam: the caller name shown with its
calls, at most 15 letters, digits, spaces and . , & -, US numbers only. Toll-free numbers are
not sold. The first month is charged when the number is active.
Returns data, the number (201). status ordering: the carrier has not assigned it yet.
Errors: 400 validation_failed or invalid_member, 402 insufficient_credits when the workspace
cannot pay the first month (error.refusal), 409 number_limit_reached (five numbers: release one first),
no_numbers_available (try another area code or city) or member_already_has_number, 503
provider_unavailable (the carrier is not set up or refused the order; nothing was charged).

numbers-list

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

List the workspace's phone numbers (not released), newest first. At most five.

GET /api/v1/calling/numbers. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
Returns data [{numberId, e164, countryIso2, numberType (local), status (ordering, active,
releasing), assignedMemberId, cnam, monthlyCredits, unpaid, orderedAt, activatedAt,
releasedAt}] and pagination {hasMore: false}. unpaid true: its monthly credits could not be
charged, and outbound calls from it are refused until they are.

numbers-release

Write. Early access: needs calling on for the workspace. DELETE https://api.ken.so/v1/calling/numbers/{numberId}

Path: numberId

Release a phone number: its monthly credits stop and the number goes back to the carrier. Only when the user asks; it cannot be bought back. Requires the workspace_settings and billing permissions.

DELETE /api/v1/calling/numbers/{numberId}. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
The paid month is not refunded. Returns data, the number with status released (also when the
carrier no longer has it or never assigned it), or 202 with status releasing when the carrier
has not taken it back yet: the number stays releasing and finishes by itself once the number
lifecycle job is on; until then you may call this operation again. 404 for a number of
another workspace, 503 provider_unavailable when the carrier is not set up.

numbers-update

Write. Early access: needs calling on for the workspace. PATCH https://api.ken.so/v1/calling/numbers/{numberId}

Path: numberId

Assign a phone number to a member (or nobody) or set its caller name (CNAM). Requires the workspace_settings permission.

PATCH /api/v1/calling/numbers/{numberId}. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
changes keys: assigned_member_id (a member id, or null to unassign) and cnam (at most 15
letters, digits, spaces and . , & -, US numbers only; null clears it). Absent keys stay.
Returns data, the number. Errors: 400 invalid_member (not an active member), 409
member_already_has_number, 409 invalid_state (being ordered or released), 503
provider_unavailable (the carrier did not take the caller name; nothing was saved), 404 for a
number of another workspace.

rates-get

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

Query: to string

Return what a call to a phone number costs per minute, in millicredits.

GET /api/v1/calling/rates?to=. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
to: the number, E.164 like +14155550100. Returns data {to, countryIso2, lineType, priced,
millicreditsPerMinute (the destination plus the rep's leg), recordingMillicreditsPerMinute
(added when recorded)}. priced false: Kenso has no price for that destination yet and it cannot
be called; both rates are null. 400 invalid_phone when to is not a phone number.

dialer-connections-ringover-connect

Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/integrations/ringover/connection

Body (json): apiKey string, webhookKey string

Connect the workspace's Ringover account with its API key, so its calls land in Kenso.

POST /api/v1/integrations/ringover/connection. Staff, or a workspace with the calls flag
(workspace admin). Sends Ken-Version 1.1. api_key: a Ringover API key (Ringover dashboard,
Developer, API keys) with the users, calls, callback and webhooks rights. Kenso checks it against
Ringover, stores it encrypted, links each Ringover user to the Kenso member with the same email and
registers Kenso's webhook on the account. Returns 201 with connection and webhook {registered, url,
events, signingKeyStored}. When Ringover refused the webhook (registered false) and signingKeyStored
is false, Kenso refuses every call until it has the key: copy the webhook key from Ringover's webhook
configuration page, run dialer-connections-delete, connect again with webhook_key, then paste the url
of that second answer into Ringover's webhook settings for those events (each connect makes a new
url). A key Ringover refuses is a validation error and nothing is stored; a workspace with Ringover
already connected is conflict.

settings-get

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

Return the workspace's calling settings: recording, consent notice, voicemail drops and calling countries.

GET /api/v1/calling/settings. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
Returns data {recordingEnabled, consentNotice (auto, always, never), voicemailDropMode (off,
manual, auto), voicemailToMobile, voicemailToMobileAcceptedByMemberId,
voicemailToMobileAcceptedAt, allowedCountries (US, CA), dncScrub, updatedAt (null while the
workspace runs on the defaults)}.

settings-update

Write. Early access: needs calling on for the workspace. PATCH https://api.ken.so/v1/calling/settings

Update the workspace's calling settings. Absent fields stay unchanged. Change them only when the user asks. Requires the workspace_settings permission.

PATCH /api/v1/calling/settings. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
changes keys (snake_case or wire camelCase): recording_enabled (bool), consent_notice (auto,
always, never), voicemail_drop_mode (off, manual, auto), voicemail_to_mobile (bool),
accept_tcpa_notice (bool), allowed_countries (non-empty list of US, CA), dnc_scrub (bool).
Null is not allowed. voicemail_to_mobile true needs accept_tcpa_notice true in the same call:
only send it after the user accepted the TCPA notice for voicemail drops to mobiles. Kenso records
who accepted and when. Returns the settings.

spend-limit-get

Read. Early access: needs calling on for the workspace. GET https://api.ken.so/v1/calling/spend-limit

Return the workspace's monthly calling spend limit and what calling spent this month.

GET /api/v1/calling/spend-limit. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
Returns data {monthlyLimitMillicredits (null is no limit; 1 credit = 1,000 millicredits),
isDefault (true at the 2,000-credit default), spentThisMonthMillicredits (call minutes and
recordings this UTC month, plus open call holds: what the cap counts; number fees are not in
it)}. Separate from the workflow spend limits.

spend-limit-update

Write. Early access: needs calling on for the workspace. PATCH https://api.ken.so/v1/calling/spend-limit

Set the workspace's monthly calling spend limit, in millicredits (null is no limit). Only when the user asks. Requires the workspace_settings and billing permissions.

PATCH /api/v1/calling/spend-limit. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
monthly_limit_millicredits: null for no limit, else 1 to 100,000,000 (2,000,000 = 2,000
credits). Returns the same shape as calling(operation="spend-limit-get").

voicemails-delete

Write. Early access: needs calling on for the workspace. DELETE https://api.ken.so/v1/calling/voicemails/{voicemailId}

Path: voicemailId

Delete one of the caller's voicemail greetings and its audio. Only when the user asks; it cannot be undone. Requires edit on the Accounts page.

DELETE /api/v1/calling/voicemails/{voicemailId}. Staff, or a workspace with the calling flag.
Sends Ken-Version 1.1. voicemail_id: from calling(operation="voicemails-list"). Returns 204 with
no body. A drop on a live call that has not played the greeting yet fails. 404 for a greeting
of another member or workspace, or one already deleted; 403 for a credential with no member.

voicemails-list

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

List the caller's own voicemail greetings, the recordings a call can drop on a voicemail.

GET /api/v1/calling/voicemails. Staff, or a workspace with the calling flag. Sends Ken-Version 1.1.
Greetings belong to the member signed in (Dialer 08): a credential with no member, like a
workspace API key, gets 403. Returns data, at most five, oldest first (the first is the one an
auto drop plays): {voicemailId, name, durationSeconds, format (wav or mp3), audioUrl (a link to
listen, valid 5 minutes, absent while Kenso's audio store is not set up), createdAt}. Uploading
a greeting and dropping one on a call happen only in the Kenso app.