Kenso MCP tools

Instagram instagram

Instagram accounts a workspace sends from: connect and reconnect through a hosted login (connect-sessions; pass instagram_account_id to reconnect), name, daily cap, time zone, working hours, pause and resume (update with paused), remove. Shows today's use per action against the ramp-lowered cap. Nothing here reads the account's chats, followers, following or posts.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through instagram_read and changes through instagram_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: people-clear-instagram, create-connect-session, delete, people-find-instagram, get, people-get-instagram, list, people-set-instagram, update

people-clear-instagram

Write. Early access: needs accounts, instagram on for the workspace. DELETE https://api.ken.so/v1/people/{personId}/instagram

Path: personId

Clear a person's Instagram handle. Deletes the workspace's stored Instagram chats with it.

DELETE /api/v1/people/{personId}/instagram. Staff while Instagram outreach is dark. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Requires Accounts edit and the instagram flag.
Removes the handle, its status and the stored Instagram account, and in the same request deletes the workspace's
stored Instagram conversations with that handle and the profile snapshot. Clearing a person with no handle changes
nothing. Candidates stay. Returns what people-get-instagram returns. A missing person, another workspace's, or a
flag that is off, is not_found.

create-connect-session

Write. Early access: needs instagram on for the workspace. POST https://api.ken.so/v1/instagram-accounts/connect-sessions

Body (json): instagramAccountId integer, name string

Start connecting a new Instagram account, or reconnect one. Returns 201 with a hosted login url. Requires Delivery edit. The person opens url and signs in to Instagram there.

POST /api/v1/instagram-accounts/connect-sessions. Staff while Instagram outreach is dark. Sends Ken-Version 1.1.
name: optional label, at most 100 characters. instagram_account_id: reconnect that account instead of adding one.
Returns { instagramAccountId, url, expiresAt }; the url works for an hour. A new account shows as connecting until
the person finishes the hosted page, then connected. A reconnect keeps the ramp, unless the account sat idle 14 days
or more. 402 plan_limit_reached when the workspace cannot pay the first month or its plan's Instagram account limit
is reached; 404 for an unknown instagram_account_id; 409 invalid_state while Instagram outreach is off for the
workspace; 503 when the connection service is unavailable (retry in a minute).

delete

Write. Early access: needs instagram on for the workspace. DELETE https://api.ken.so/v1/instagram-accounts/{instagramAccountId}

Path: instagramAccountId

Remove an Instagram account from Kenso. Returns 204. Requires Delivery edit. Its monthly credits stop.

DELETE /api/v1/instagram-accounts/{instagramAccountId}. Staff while Instagram outreach is dark. Sends Ken-Version 1.1.
Kenso deletes the account at the connection service, then removes it; conversations with people in the workspace
stay as their history. 503 when the connection service is rate limited: nothing was deleted, retry.

people-find-instagram

Write. Early access: needs accounts, instagram on for the workspace. POST https://api.ken.so/v1/people/{personId}/instagram/find

Path: personId

Find a person's Instagram handle from what Kenso knows and the web. Saves candidates for review. Free during the beta. Never opens Instagram and never returns a chat. Read the result with people-get-instagram.

POST /api/v1/people/{personId}/instagram/find. Staff while Instagram outreach is dark. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Requires Accounts edit and the instagram flag.
Runs in the request: links Kenso already holds (the person's LinkedIn text and their research), then at most two web
searches on instagram.com, then one Oriane lookup, stopping at the first strong match. Each workspace gets 500
searches and 200 Oriane lookups a day. Returns what people-get-instagram returns: needs_review with up to 3
candidates for a person to accept or reject, or not_found. incomplete true means a step could not finish (or the
daily allowance is spent) and nothing was found: nothing is saved, so find again later. A person whose handle is
accepted is invalid_state: clear it first. service_unavailable when discovery cannot reach its providers: retry in a
few minutes. A missing person, another workspace's, or a flag that is off, is not_found.

get

Read. Early access: needs instagram on for the workspace. GET https://api.ken.so/v1/instagram-accounts/{instagramAccountId}

Path: instagramAccountId

Return one Instagram account in the current workspace. A missing or cross-workspace id is not_found.

GET /api/v1/instagram-accounts/{instagramAccountId}. Staff while Instagram outreach is dark. Sends Ken-Version 1.1.
Requires Delivery view. The account has the fields instagram(operation="list") describes: its own profile and
Kenso's state, never its chats, followers, following or posts.

people-get-instagram

Read. Early access: needs accounts, instagram on for the workspace. GET https://api.ken.so/v1/people/{personId}/instagram

Path: personId

Read a person's Instagram handle, its status, the discovery candidates and the stored profile's basics. Nothing runs. Start a search with people-find-instagram. Never returns a chat, a follower list or a raw profile.

GET /api/v1/people/{personId}/instagram. Staff while Instagram outreach is dark. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Requires Accounts view and the instagram flag.
Returns personId, handle (the accepted username, else null), status (verified: accepted from a candidate; manual:
set by hand; needs_review: candidates wait for a person; not_found: searched, none found, searched again after 60
days; rejected; null: never searched), source (links, firecrawl_search, oriane or manual), checkedAt,
userIdResolved (true when the handle is matched to its Instagram account; the id itself is never returned),
incomplete (true only on a find that could not finish), candidates [{id, handle, source, score, signals, snippet,
status, createdAt}] (signals: company_domain_link, bio_names_company, linked_from_linkedin_or_site,
exact_full_name, location_match, bio_matches_title, handle_has_first_and_last; status candidate, accepted or
rejected) and snapshot (null, or {fetchedAt, displayName, profilePictureUrl, bio, followerCount, isVerified} once
the handle is accepted and a profile was read). An accepted handle does not follow a person merge. A missing
person, another workspace's, or a flag that is off, is not_found; a merged person is not_found with detail
person_merged.

list

Read. Early access: needs instagram on for the workspace. GET https://api.ken.so/v1/instagram-accounts

Query: cursor string, limit integer

List Instagram accounts in the current workspace. Requires Delivery view and the instagram flag. Nothing here reads the account's chats, followers or posts.

GET /api/v1/instagram-accounts. Staff while Instagram outreach is dark. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. limit is 1-200 (default 50); pass pagination.nextCursor as cursor.
Each account: id, name, status (connecting, connected, disconnected, locked, error), healthStatus, username,
displayName, profilePictureUrl, bio, dailyCap (the workspace's setting), effectiveDailyCap (the cap today, lowered
during the four-week ramp), hourlyCap, rampStage (0 before the first connect, 1-4 ramping, 5 full volume),
rampStartedAt, rampSchedule (five weeks of { week, start, end, cap }, dates yyyy-MM-dd), usage ({ countedToday,
usedThisHour, nextActionAt, kinds: [{ kind, used, cap }] } with kind follow, like, comment, new_dm, dm or read; cap
null when the kind has no cap of its own), throttledUntil (when Instagram's throttle lifts, else null), paused,
pausedAt, timezone, workingHours ({ mon..sun: { open, start, end } }, null until set), connectedByUserId,
connectedByMemberId and createdAt. Only the account's own profile and Kenso's state: no chats, followers,
following or posts.

people-set-instagram

Write. Early access: needs accounts, instagram on for the workspace. PUT https://api.ken.so/v1/people/{personId}/instagram

Path: personId

Body (json): acceptCandidateId integer, handle string, rejectCandidateId integer

Set a person's Instagram handle, accept one of the candidates, or reject one. Pass exactly one. Replacing or rejecting a handle deletes the workspace's stored Instagram chats with it. Never returns a chat.

PUT /api/v1/people/{personId}/instagram. Staff while Instagram outreach is dark. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Requires Accounts edit and the instagram flag.
handle: an Instagram username or profile URL (status manual). accept_candidate_id: a candidate id from
people-get-instagram (status verified). reject_candidate_id: marks that candidate rejected; when it is the accepted
handle, the handle is cleared and the status becomes rejected, and when it was the last open candidate the status
becomes rejected. Setting or accepting reads the profile once to resolve its Instagram account so the person's chats
can be matched; with no connected Instagram account, or when Instagram is busy, the handle is saved and matched
later. Replacing or rejecting an accepted handle deletes the workspace's stored Instagram conversations and the
snapshot for it in the same request. validation_failed: not exactly one of the three, a bad username, a username no
Instagram account has, or a candidate that is not on this person. instagram_handle_taken (409): another person of the
workspace already has this handle or is this Instagram account. Returns what people-get-instagram returns.

update

Write. Early access: needs instagram on for the workspace. PATCH https://api.ken.so/v1/instagram-accounts/{instagramAccountId}

Path: instagramAccountId

Body (json): dailyCap integer, name string, paused boolean, timezone string, workingHours object

Update an Instagram account's name, daily cap, time zone, working hours or pause. Absent fields stay unchanged. Requires Delivery edit.

PATCH /api/v1/instagram-accounts/{instagramAccountId}. Staff while Instagram outreach is dark. Sends Ken-Version 1.1.
name: at most 100 characters; "" clears it.
daily_cap: 1-100 counted actions a day; the ramp lowers it during the first four weeks.
timezone: an IANA id such as Europe/Bucharest; "" clears it (UTC).
working_hours: all seven days, e.g. {"mon": {"open": true, "start": "09:00", "end": "17:00"}, ...,
"sun": {"open": false}}.
paused: true pauses automated actions from the account (a second pause keeps the first pausedAt); false resumes them.
Invalid values are 400 validation_failed naming each field. Returns the account.