Kenso MCP tools

Facebook facebook

Personal Facebook accounts a workspace sends from: connect and reconnect through a hosted login, time zone, working hours, the mutual-friend floor and the per-action ramp, pause and resume, remove. Each account costs 1,500 credits a month. Nothing here reads the account's chats, friends or posts.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through facebook_read and changes through facebook_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: create-connect-session, create-reconnect-session, delete, get, list, pause, reset-ramp, resume, update

create-connect-session

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

Start connecting a new Facebook account. Returns 201 with a hosted login url. Requires Delivery edit. The person opens url and signs in to Facebook there.

POST /api/v1/facebook-accounts/connect-sessions. Staff while Facebook outreach is dark. Sends Ken-Version 1.1.
Returns { facebookAccountId, url, expiresAt }; the url works for an hour. The account shows as connecting until the
person finishes the hosted page, then connected. Each connected account costs 1,500 credits a month.
402 plan_limit_reached when the workspace cannot pay the first month; 409 invalid_state while Facebook outreach
is off in config; 503 when the connection service is unavailable (retry in a minute).

create-reconnect-session

Write. Early access: needs facebook_outreach on for the workspace. POST https://api.ken.so/v1/facebook-accounts/{facebookAccountId}/reconnect-sessions

Path: facebookAccountId

Start a hosted session that reconnects a Facebook account. Returns 201 with a url. Requires Delivery edit.

POST /api/v1/facebook-accounts/{facebookAccountId}/reconnect-sessions. Staff while Facebook outreach is dark.
Sends Ken-Version 1.1. Returns { facebookAccountId, url, expiresAt }, like a connect session. The ramp stays where
it was; an account recovering from a Facebook restriction restarts its ramp today.

delete

Write. DELETE https://api.ken.so/v1/facebook-accounts/{facebookAccountId}

Path: facebookAccountId

Remove a Facebook account from Kenso. Returns 204. Requires Delivery edit. Its monthly credits stop.

DELETE /api/v1/facebook-accounts/{facebookAccountId}. Works with Facebook outreach off, so a workspace can remove an
account after its flag goes off. Sends Ken-Version 1.1. Kenso deletes the account at the connection service and deletes its stored private chats; chats with people in
the workspace stay as their history. 503 when the connection service is rate limited: nothing was deleted, retry.

get

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

Path: facebookAccountId

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

GET /api/v1/facebook-accounts/{facebookAccountId}. Staff while Facebook outreach is dark. Sends Ken-Version 1.1.
Requires Delivery view. The account has the fields facebook(operation="list") describes.

list

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

Query: cursor string, limit integer

List Facebook accounts in the current workspace. Requires Delivery view and the facebook_outreach flag.

GET /api/v1/facebook-accounts. Staff while Facebook 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, displayName, profileUrl, profileImageUrl (null for now), status (connecting, connected,
credentials_error, restricted, disconnected, deleted, connect_failed), statusReason (Facebook's restriction while
restricted, else null), historyUnlocked, timezone, workingHours ({ mon..sun: { open, start, end } }, null until
set, when the default applies), minMutualFriends (0-50), paused, pausedAt, connectedByUserId, rampStartedAt,
createdAt, and ramp: one row per action (message, friend_request, like, comment, follow) with action, todayCap,
start, stepPerWeek, ceiling, weekIndex (0 in the first week) and fullVolumeOn (yyyy-MM-dd).

pause

Write. POST https://api.ken.so/v1/facebook-accounts/{facebookAccountId}/pause

Path: facebookAccountId

Pause automated actions from a Facebook account. Requires Delivery edit. A person's replies from the inbox still send.

POST /api/v1/facebook-accounts/{facebookAccountId}/pause. Works with Facebook outreach off. Sends Ken-Version 1.1.
Messages, friend requests, likes, comments and follows wait and continue when the account is resumed. A second
pause keeps the first pausedAt. Returns the account.

reset-ramp

Write. Early access: needs facebook_outreach on for the workspace. POST https://api.ken.so/v1/facebook-accounts/{facebookAccountId}/ramp/reset

Path: facebookAccountId

Restart a Facebook account's ramp from today with its current plan. Requires Delivery edit.

POST /api/v1/facebook-accounts/{facebookAccountId}/ramp/reset. Staff while Facebook outreach is dark.
Sends Ken-Version 1.1. Every action goes back to its start value this week. Returns the account.

resume

Write. Early access: needs facebook_outreach on for the workspace. POST https://api.ken.so/v1/facebook-accounts/{facebookAccountId}/resume

Path: facebookAccountId

Resume automated actions from a paused Facebook account. Requires Delivery edit.

POST /api/v1/facebook-accounts/{facebookAccountId}/resume. Staff while Facebook outreach is dark. Sends Ken-Version 1.1.
Clears pausedAt; the waiting actions continue where they stopped. Returns the account.

update

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

Path: facebookAccountId

Body (json): minMutualFriends integer, ramp object, timezone string, workingHours object

Update a Facebook account's time zone, working hours, mutual-friend floor or ramp. Absent fields stay unchanged. Requires Delivery edit.

PATCH /api/v1/facebook-accounts/{facebookAccountId}. Staff while Facebook outreach is dark. Sends Ken-Version 1.1.
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}}.
min_mutual_friends: 0-50; friend requests go only to people with at least this many mutual friends.
ramp: per action (message, friend_request, like, comment, follow) {start, step_per_week, ceiling}; give only
the fields to change. Each value above the action's hard ceiling is lowered to it (message 50, friend_request 25,
like 30, comment 10, follow 20). Editing the ramp keeps its start date; facebook(operation="reset-ramp") restarts it.
Invalid values are 400 validation_failed naming each field (invalid_timezone, missing_day, invalid_time,
out_of_range, unknown_action). Example: ramp={"message": {"ceiling": 40}}.