Kenso MCP tools

Infra infra

Fleet cleanup of sending infrastructure: billing leaks, idle or expiring domains, disconnected inboxes and renewal shortfalls. Pausing or changing one inbox or domain is inboxes or domains update. Findings: summary and findings read them; snooze, ignore and reopen change their status (nothing changes at a provider). Fixes: bulk inbox and domain actions (pause, resume, daily limit, connection check, link domain, delete, provider cancel, domain auto-renew off): preview first and show the user what changes, what is skipped and which live campaigns lose sending, then run with the preview token; batches and batch follow it. A batch that takes sending from a live client campaign needs that client's yes first. These work per workspace (needs the infra_findings flag) and for Kenso staff across workspaces; the fleet lists inboxes, domains and provider-accounts, and sweep, are for Kenso staff.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through infra_read and changes through infra_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: run, preview, findings, batch, ignore, batches, reopen, snooze, summary

run

Write. Early access: needs infra_findings on for the workspace. POST https://api.ken.so/v1/infra/action-batches

Body (json): acknowledgeLiveCampaigns boolean, action string, previewToken string, targets object

Run a previewed bulk action as an audited batch. A batch that takes sending from a live client campaign needs that client's yes first.

Workspace: POST /api/v1/infra/action-batches with X-Ken-Workspace-Id (client_id, else the session's workspace),
behind the infra_findings flag. Staff: POST /api/v1/admin/infra/action-batches, for a staff preview; client_id is
not sent. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Returns 202 with the queued batch; Kenso runs it in the background, one inbox or domain at a time, and writes an
audit line for each. Follow it with infra(operation="batch", batch_id=...).
Before you run: when the preview lists live campaigns (totals.liveCampaignsAffected > 0), the batch pauses,
deletes or moves inboxes those campaigns send from. Get a yes from each of those clients that names the client,
then pass acknowledge_live_campaigns=true. Without it the run is refused with live_campaigns_not_acknowledged,
listing each campaign by workspace and name.
preview_token: from infra(operation="preview"). One run per preview, by the same actor, in the same workspace
(a staff preview runs as staff), before it expires. action, inbox_ids and domain_ids are optional echoes: when
sent they must match the preview (order does not matter), else preview_mismatch.
409 codes: preview_used, preview_expired, preview_mismatch, live_campaigns_not_acknowledged, nothing_to_run.
403 preview_actor_mismatch: the preview was made by someone else, or in the Kenso app. 404: no such preview here.
503: batch processing is switched off; the preview stays valid until it expires.
A provider failure (the mailbox vendor or the mail provider) leaves that item failed and nothing recorded; preview
and run again for the failed ids.

preview

Write. Early access: needs infra_findings on for the workspace. POST https://api.ken.so/v1/infra/action-previews

Body (json): action string, parameters object, targets object

Preview a bulk inbox or domain action: pause, resume, daily limit, connection check, link domain, delete, provider cancel, domain auto-renew off. Changes nothing. Returns a preview_token for run (valid 15 minutes), what each inbox or domain would change or why it is skipped, and the live campaigns that would lose sending. Full docs: describe_tools(['api_infra_action_previews_create'])

Workspace: POST /api/v1/infra/action-previews with X-Ken-Workspace-Id (client_id, else the session's workspace).
Needs the infra_findings flag on the workspace (404 while it is off, reported as "Infra findings are not enabled
for this workspace") and Delivery edit. inbox_ids and domain_ids must be from this workspace: an id from another
workspace comes back as an item skipped with not_found and is never touched.
Staff: POST /api/v1/admin/infra/action-previews, no workspace header and no flag: ids may come from any workspace,
each item names its workspace, and the staff-only actions are open. client_id is not sent.
Sends Ken-Version 1.1 and X-Ken-Actor: agent.
inbox_ids and domain_ids: up to 1,000 ids together.
limit: the new daily limit for set_daily_limit, 0 or more.
target_workspace_id (staff): the workspace move_workspace moves the inboxes or domains to.
Actions (each item previews what changes, or why it is skipped):
- pause_sending, resume_sending: inboxes. Pausing takes the inbox out of its campaigns' sending.
- set_daily_limit: inboxes; needs limit.
- check_connection: inboxes with a connection; re-verifies the sign-in.
- retire: inboxes, to receive-only. Staff only.
- delete_inbox: inboxes. Deletes the Kenso inbox and cancels its bought mailbox; needs the agent_send flag and
  the Billing feature on a workspace call. Never deletes a member's own Google or Microsoft account.
- cancel_at_provider: inboxes or domains already deleted in Kenso that a provider still bills; needs Billing.
  An inbox: cancels its bought mailbox. A domain: turns auto-renew off at Kenso's registrar, so it lapses at
  expiry; skipped when Kenso did not buy it (not_ken_purchased), when it is a Kenso brand or shared redirect domain
  (ken_owned_domain), while another live Kenso row uses the name (domain_in_use) or when the registrar does not
  hold it (not_at_registrar). The action does not check reply capture; a billing_leak finding already leaves out an
  inbox or domain that can still receive replies, so run it on the ids those findings name.
- uncancel_at_provider: Google mailboxes scheduled for cancellation. Staff only.
- domain_auto_renew_off: domains Kenso bought, with no live inbox left; needs Billing.
- link_domain: inboxes not yet linked to their domain's row.
- move_workspace: inboxes or domains to target_workspace_id. Staff only; a domain moves with its inboxes.
The billing checks of a workspace call do not apply to staff; a staff delete_inbox needs no agent_send flag.
Response data: previewToken, expiresAt (UTC), action, totals {selected, willRun, skipped,
liveCampaignsAffected, monthlySavingCents}, and items [{subjectType (inbox|domain), subjectId, subjectLabel,
workspaceId, workspaceName, status (pending = will run, skipped), change, skippedReason, isCuttingSending,
liveCampaigns [{campaignId, campaignName, workspaceId, workspaceName}], monthlySavingCents}].
Show the user the totals, every skipped reason and every live campaign before you call
infra(operation="run", preview_token=...).
403 codes: staff_only_action (retire, uncancel_at_provider, move_workspace on a workspace call), forbidden
(Billing missing).

findings

Read. Early access: needs infra_findings on for the workspace. GET https://api.ken.so/v1/infra/findings

Query: cursor string, kind string, limit integer, severity string, status string

List infrastructure findings: billing leaks, idle domains, disconnected inboxes and the rest. A workspace with the infra_findings flag lists its own (default status open); Kenso staff list every workspace or one (workspace_id). Comma-separated values mean OR. Read-only.

Workspace: GET /api/v1/infra/findings with X-Ken-Workspace-Id (client_id, else the session's workspace).
Needs the infra_findings flag; 404 while it is off, reported as "Infra findings are not enabled for this
workspace". Staff: GET /api/v1/admin/infra/findings, with workspace_id (or client_id) as the workspaceId
filter (both omitted = every workspace; two different values are refused) and provider as an extra filter.
Sends Ken-Version 1.1.
kind: billing_leak, provider_cancelled, warmup_missing, idle_domain, domain_expiring, inbox_no_domain,
disconnected_inbox, renewal_shortfall, registrar_orphan. severity: critical, warning, info.
status: open (default for a workspace), snoozed, ignored, resolved. provider (staff only): the provider lane code shown on each finding; providerKind is its neutral name.
Each value list may be comma-separated, for example kind="billing_leak,idle_domain".
limit is 1 to 200 (default 50); pass the cursor from pagination.nextCursor while pagination.hasMore.
Returns a list of { id, workspaceId, workspaceName (staff), kind, subjectType (inbox|domain|provider_account|
registrar_domain), subjectId, subjectKey, provider, severity, status, title, evidence (object),
suggestedAction, monthlyCost, firstSeenAt, lastSeenAt, resolvedAt, snoozedUntil }.
suggestedAction is one of pause_sending, resume_sending, set_daily_limit, check_connection, retire,
delete_inbox, cancel_at_provider, uncancel_at_provider, domain_auto_renew_off, link_domain,
move_workspace, top_up_wallet, import_domain, renew_domain, enable_warmup. The first eleven are bulk actions:
infra(operation="preview", action=..., inbox_ids=[...]) then infra(operation="run", preview_token=...).
A finding nobody needs to act on now: infra(operation="snooze", finding_id=..., days=...),
infra(operation="ignore", finding_id=...), and infra(operation="reopen", finding_id=...) to undo either.

batch

Read. Early access: needs infra_findings on for the workspace. GET https://api.ken.so/v1/infra/action-batches/{batchId}

Path: batchId

Read one bulk action batch with every item's outcome.

Workspace: GET /api/v1/infra/action-batches/{batchId} with X-Ken-Workspace-Id (client_id, else the session's
workspace), behind the infra_findings flag; another workspace's batch is 404. Staff: GET
/api/v1/admin/infra/action-batches/{batchId}, any batch; client_id is not sent.
Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Returns the batch (as in infra(operation="batches")) with items: status (pending|running|succeeded|failed|skipped),
change, skippedReason, error (why a failed item failed), liveCampaigns and processedAt.

ignore

Write. Early access: needs infra_findings on for the workspace.

Ignore an infrastructure finding: it stays ignored until reopened, and the sweep never resolves it. Nothing changes at a provider.

Workspace: PATCH /api/v1/infra/findings/{findingId} with X-Ken-Workspace-Id (client_id, else the session's
workspace). Needs the infra_findings flag (404 while it is off, reported as "Infra findings are not enabled for
this workspace") and Delivery edit; another workspace's finding is 404. Staff: PATCH
/api/v1/admin/infra/findings/{findingId}, any workspace's finding; client_id and workspace_id are not sent.
Sends Ken-Version 1.1.
finding_id: the id from infra(operation="findings"). Sends { status: "ignored" }.
An ignored finding leaves the open list and stays ignored until infra(operation="reopen", finding_id=...): the
sweep keeps seeing it but never reopens or resolves it. Use it for a finding that is expected (for example an
idle domain kept on purpose). Nothing changes at a provider: the inbox, domain or bill stays as it is.
Returns the finding (as in findings), status "ignored". The backend records who changed it.
403 forbidden: a billing_leak on the workspace route (Kenso pays it and fixes it; only Kenso staff snooze or ignore
one). 409 invalid_state: the finding is resolved.

batches

Read. Early access: needs infra_findings on for the workspace. GET https://api.ken.so/v1/infra/action-batches

Query: cursor string, limit integer

List bulk action batches, newest first: a workspace's own, or for Kenso staff every workspace's or one's.

Workspace: GET /api/v1/infra/action-batches with X-Ken-Workspace-Id (client_id, else the session's workspace).
Needs the infra_findings flag and Delivery view; staff batches across workspaces are not listed here.
Staff: GET /api/v1/admin/infra/action-batches, with workspace_id (or client_id) as the workspaceId filter, never
X-Ken-Workspace-Id (both omitted = every batch, staff and workspace ones; two different values are refused).
Sends Ken-Version 1.1 and X-Ken-Actor: agent. limit 1-200 (default 50), cursor from pagination.nextCursor.
Each batch: id, action, parameters, status (previewed|queued|running|finished), actor {type
(user|api_key|mcp|system), userId, label}, hasAcknowledgedLiveCampaigns, totals {selected, willRun, skipped,
succeeded, failed, pending, liveCampaignsAffected, monthlySavingCents}, createdAt, queuedAt, startedAt,
finishedAt.

reopen

Write. Early access: needs infra_findings on for the workspace.

Reopen a snoozed or ignored infrastructure finding now. Nothing changes at a provider.

Workspace: PATCH /api/v1/infra/findings/{findingId} with X-Ken-Workspace-Id (client_id, else the session's
workspace). Needs the infra_findings flag (404 while it is off, reported as "Infra findings are not enabled for
this workspace") and Delivery edit; another workspace's finding is 404. Staff: PATCH
/api/v1/admin/infra/findings/{findingId}, any workspace's finding; client_id and workspace_id are not sent.
Sends Ken-Version 1.1.
finding_id: the id from infra(operation="findings"). Sends { status: "open" }.
The finding is back on the open list at once, snoozedUntil cleared. Snoozed findings reopen by themselves on
the first sweep after their date; ignored ones stay ignored until reopened here. Nothing changes at a provider.
Returns the finding (as in findings), status "open". The backend records who changed it.
409 invalid_state: the finding is resolved (a resolved finding comes back as a new one if the sweep sees it again).

snooze

Write. Early access: needs infra_findings on for the workspace.

Snooze an infrastructure finding until a date (snoozed_until) or for a number of days (1 to 365). It reopens on the first sweep after that date. Nothing changes at a provider.

Workspace: PATCH /api/v1/infra/findings/{findingId} with X-Ken-Workspace-Id (client_id, else the session's
workspace). Needs the infra_findings flag (404 while it is off, reported as "Infra findings are not enabled for
this workspace") and Delivery edit; another workspace's finding is 404. Staff: PATCH
/api/v1/admin/infra/findings/{findingId}, any workspace's finding; client_id and workspace_id are not sent.
Sends Ken-Version 1.1.
finding_id: the id from infra(operation="findings").
Pass exactly one of snoozed_until (ISO 8601; a time without an offset is read as UTC; in the future and at most
365 days ahead) or days (a whole number, 1 to 365, counted from now). Sends { status: "snoozed", snoozedUntil }.
A snoozed finding leaves the open list and opens again on the first sweep after snoozedUntil. Snoozing an
already snoozed finding moves the date. Nothing changes at a provider: the inbox, domain or bill stays as it is.
Returns the finding (as in findings), status "snoozed" and snoozedUntil set. The backend records who changed it.
400 validation_error: a date in the past or more than a year ahead. 403 forbidden: a billing_leak on the
workspace route (Kenso pays it and fixes it; only Kenso staff snooze or ignore one). 409 invalid_state: the finding
is resolved.

summary

Read. Early access: needs infra_findings on for the workspace. GET https://api.ken.so/v1/infra/summary

Counts of open infrastructure findings and the monthly cost at stake. A workspace with the infra_findings flag reads its own; Kenso staff read every workspace or one (workspace_id). snooze, ignore and reopen change a finding's status; preview then run fixes what it found.

Workspace: GET /api/v1/infra/summary with X-Ken-Workspace-Id (client_id, else the session's workspace).
Needs the infra_findings flag on the workspace; 404 while it is off, reported as "Infra findings are not
enabled for this workspace". Staff: GET /api/v1/admin/infra/summary, with workspace_id (or client_id) as the
workspaceId filter (both omitted = every workspace; two different values are refused). Sends Ken-Version 1.1.
Returns { openCount, snoozedCount, bySeverity: { critical, warning, info },
byKind: [{ kind, openCount, critical, warning, info, monthlyCost }],
monthlyCostAtStake: { amount, currency } }. Money is { amount (cents), currency: "usd" }.
Staff also get lastSweep: { sweepId, trigger (schedule|staff), status (running|completed|failed), startedAt,
finishedAt, detectors: [{ kind, subjectType, outcome (completed|failed|skipped), found, opened, resolved,
error }], error }. Only a completed detector resolves findings.