Kenso MCP tools

Jobs jobs

Status, results and cancel of Kenso jobs (contact imports and exports, crawls, ...); job_type is required.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through jobs_read and changes through jobs_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: cancel, get, list

cancel

Write. POST https://api.ken.so/v1/jobs/{jobId}/cancel

Path: jobId

Query: type string

Cancel a job when its type supports cancellation. Crawl and batch_scrape can be canceled. Extraction returns 409 invalid_state.

POST /api/v1/jobs/{jobId}/cancel with Ken-Version 1.1 and
X-Ken-Workspace-Id. Public in the catalog. The backend requires Search edit access (owners, admins and editors by default)
plus what the job type's own routes need (as on jobs.list); a migration job needs the integrations
permission (workspace admin).

job_type is required and is sent as the type query parameter.
Crawl and batch_scrape cancel the stored Firecrawl id. Extraction and the
other types return 409 invalid_state when the job exists. A missing job
is not_found. A job from another workspace is not_found before any
Firecrawl call.

get

Read. GET https://api.ken.so/v1/jobs/{jobId}

Path: jobId

Query: cursor string, type string

Return one job. job_type is required because the same numeric id can exist for another type.

GET /api/v1/jobs/{jobId} with Ken-Version 1.1 and X-Ken-Workspace-Id.
Public. job_type is sent as the type query parameter. A missing or
cross-workspace id is not_found. The type needs the same page or feature
as on jobs list (crawl output needs Search view), else 403
permission_denied before any job is read. A completed domain_health job
includes domainsListed, including 0. It is omitted until that count exists. Other
job types do not get the field. A campaign contact_import job includes skipped:
the rows it dropped by reason, including 0 (duplicateInCampaign,
duplicateInOtherCampaign, duplicateInSource, alreadyContacted, blocklist,
failedValidation, salesNavigatorProfileUnresolved, other, and for a csv
import created with List check fixes missingKey, invalidEmail, noMx,
catchAll, personalEmail, roleAddress, companyContacted, companyCap); a
people import has personImport instead. For crawl, extraction, and batch_scrape,
the read refreshes that workspace's job from Firecrawl and result is the
upstream payload. A crawl or batch_scrape result holds one page: when
result.next is set, pass it back as cursor to read the next page. An
inbox_import job includes inboxImport: connectedCount,
failedCount, skippedCount, startedAt, updatedAt, completedAt and rows
(index, email, status connected/failed/skipped, inboxId, errorCode,
message). An inbox_import with no progress for 10 minutes is failed with
error.code interrupted; one that stopped because the inbox_csv_import flag
went off or the caller lost delivery edit is failed with error.code
feature_disabled or forbidden. A knowledge_export job is its requester's
only: another member gets not_found. Its downloadUrl needs Ken-Version 1.1,
X-Ken-Workspace-Id and the member's credentials, so the Kenso app fetches it;
it is not a link to open in a browser (knowledge_library(operation=
"export-content") downloads it). Envelope: success plus data.

list

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

Query: cursor string, limit integer, status string, type string

List jobs of one type in the current workspace. job_type is required: contact_import, contact_export, domain_health, lead_scoring, enrichment, crawl, extraction, batch_scrape, knowledge_export, inbox_import, or migration.

GET /api/v1/jobs with Ken-Version 1.1 and X-Ken-Workspace-Id. Public.

job_type is required because numeric ids collide across sources. It is
sent as the type query parameter: contact_import, contact_export, domain_health,
lead_scoring, enrichment, crawl, extraction, batch_scrape, knowledge_export,
inbox_import, or migration.
status is an optional comma-separated OR filter: queued, running,
succeeded, failed, canceled. limit is 1..200; omit it for the backend
default of 50. A completed domain_health job includes domainsListed,
including 0. It is omitted until that count exists. Other job types do
not get the field. Envelope: success, data array, pagination.

Each type also needs what its own routes need, else 403
permission_denied: crawl, extraction and batch_scrape need Search view;
domain_health Delivery view; contact_import, lead_scoring and enrichment
Campaigns view; contact_export Campaigns view and the Export feature;
knowledge_export Knowledge view; migration workspace Admin. inbox_import
needs only membership.