Kenso MCP tools

Members members

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through members_read and changes through members_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: activate, invitations-create, deactivate, invitations-delete, delete, workspaces-delete-wordmark, invitations-get, get, invitations-list, list, list-activity, purchase, workspaces-replace-wordmark, resend, workspaces-transfer-ownership, update, create_workspace_invitation, invite

activate

Write. POST https://api.ken.so/v1/members/{memberId}/activate

Path: memberId

Confirm a member is active in the current workspace. Returns the member unchanged; it never switches the account on.

POST /api/v1/members/{memberId}/activate with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. Envelope: success plus data.
Needs the members permission. A user who is not a member of the
workspace, or whom the members list does not show, is 404. Being a member is what makes someone active in a
workspace, so a deactivated member comes back through
workspace(operation="members-create") or an invitation. Only Kenso staff
switch a whole account on or off (DEV-2567).

invitations-create

Write. POST https://api.ken.so/v1/invitations

Body (json): email string, role string, templateId integer

Invite someone to the current workspace. Omitted role means member. This sends the provider invitation email.

POST /api/v1/invitations with Ken-Version 1.1 and X-Ken-Workspace-Id.
Internal exposure. The backend requires the members permission and sends
the provider invitation email.

email is required. role is admin, member, view_only, client, or
network_member (someone outside the team who lends their LinkedIn network:
their own LinkedIn, the Network page and the messages they approve; refused
with 400 until Network members are on). Omit role to invite a member. template_id (optional, permissions(operation="list")) wins
over role: the person joins on that permission template; an unknown
template is 404. A new invitation is HTTP 201. Envelope: success plus data.
The returned id is the provider invitation id.

deactivate

Write. POST https://api.ken.so/v1/members/{memberId}/deactivate

Path: memberId

Deactivate a member in the current workspace only. Removes them from this workspace; their account and other workspaces stay.

POST /api/v1/members/{memberId}/deactivate with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. Envelope: success plus data, the
member with isActive false. Needs the members permission. A user the
members list does not show is not_found. Yourself and the last admin are
refused, and a Kenso staff member on the list is 403 forbidden
(error.details[0].code staff_member_protected) unless the caller is
staff. While the permissions flag is on, the workspace owner (isOwner
true) is 409 owner_protected unless the caller is the owner or staff.
Only Kenso staff switch a whole account off (DEV-2567).

invitations-delete

Write. DELETE https://api.ken.so/v1/invitations/{invitationId}

Path: invitationId

Revoke a pending invitation. Empty success means the invitation was revoked.

DELETE /api/v1/invitations/{invitationId} with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. The backend returns 204 with
an empty body. invitation_id is the provider invitation id (uinv_...)
from members(operation="invitations-list"); a numeric Kenso id is refused.

delete

Write. DELETE https://api.ken.so/v1/members/{memberId}

Path: memberId

Remove a member from the current workspace. Empty success means the member was removed.

DELETE /api/v1/members/{memberId} with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. The backend requires a
workspace admin and returns 204 with an empty body. A user the members
list does not show is not_found, and nothing changes. While the
permissions flag is on, removing the workspace owner (isOwner true) is
409 owner_protected unless the caller is the owner or Kenso staff.

workspaces-delete-wordmark

Write. DELETE https://api.ken.so/v1/workspaces/{workspaceId}/wordmark

Path: workspaceId

Remove the workspace's wide logo (wordmark). Empty success means it was removed; wide surfaces then show the square icon.

DELETE /api/v1/workspaces/{workspaceId}/wordmark with Ken-Version 1.1.
Internal exposure. The backend returns 204 with an empty body.

invitations-get

Read. GET https://api.ken.so/v1/invitations/{invitationId}

Path: invitationId

Return one invitation in the current workspace. invitation_id is the provider invitation id.

GET /api/v1/invitations/{invitationId} with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. Pass the provider id (uinv_...)
from members(operation="invitations-list"), not a numeric Kenso id: a
numeric id is refused. Envelope: success plus data.

get

Read. GET https://api.ken.so/v1/members/{memberId}

Path: memberId

Return one member of the current workspace. member_id is the Kenso user id. A missing member is not found.

GET /api/v1/members/{memberId} with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. member_id is the Kenso user id.
Envelope: success plus data. isOwner is true when the member is the
workspace owner. jobTitle and linkedinUrl are omitted when unset
(DEV-10774). A user the members list does not show is not_found.

invitations-list

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

Query: cursor string, limit integer

List pending and expired invitations for the current workspace. Newest first. The backend requires a workspace admin.

GET /api/v1/invitations with Ken-Version 1.1 and X-Ken-Workspace-Id.
Internal exposure. Ordered newest first. The provider caps each status.

limit is 1..200; omit it for the backend default of 50. cursor is
pagination.nextCursor. Envelope: success, data array, pagination.

list

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

Query: cursor string, limit integer

List members of the current workspace. client_id is required unless a workspace is already pinned.

GET /api/v1/members with Ken-Version 1.1 and X-Ken-Workspace-Id.
Internal exposure. Ordered by member id.

limit is 1..200; omit it for the backend default of 50. cursor is
pagination.nextCursor. Envelope: success, data array, pagination.
isOwner is true on the workspace owner only: the stored owner while they
are an active member on the Admin template (DEV-5562). jobTitle and
linkedinUrl come from the member's profile and are omitted when unset
(DEV-10774); linkedinUrl is as they saved it, unchecked.

list-activity

Read. GET https://api.ken.so/v1/members/activity

Query: cursor string, limit integer

List when each member of the current workspace was last active in Kenso. Needs the members permission. Pages like the members list.

GET /api/v1/members/activity with Ken-Version 1.1 and X-Ken-Workspace-Id.
Internal exposure. Read-only. Needs the members permission; anyone else
gets 403 permission_denied.

Pages exactly like members(operation="list"): the same members, ordered by
member id, limit 1..200 (default 50), cursor is pagination.nextCursor. Page
N of both lists names the same members, so join them on memberId (the
member's id). Envelope: success, data array of {memberId, lastActiveAt},
pagination.

lastActiveAt is the UTC time the person last used the Kenso app, from any
of their sign-ins (signed-out ones included) and in any workspace, since a
sign-in belongs to the person. It is null when they have not signed in
since the session registry went live on 2026-10-29, and always null for a
Kenso staff member unless the caller is staff. API key and MCP use do
not count. It moves at most once a minute.

purchase

Write. POST https://api.ken.so/v1/billing/seats

Body (json): purchaseId string, quantity integer

Retired: LinkedIn seats are no longer sold. Refused for every plan. On Platform and Dfy each connected LinkedIn account costs 1,500 credits ($30) per month.

POST /api/v1/billing/seats is not called. DEV-1544 B03 refuses the $49
LinkedIn seat for every plan, so this tool refuses before any request. The
refusal covers every plan: on Platform and Dfy, seats are unlimited and
each connected LinkedIn account costs 1,500 credits ($30) per month; Free
upgrades to Platform first; on VIP (Premium), extra seats go through
billing checkout extras. quantity, purchase_id and client_id are ignored.

workspaces-replace-wordmark

Write. PUT https://api.ken.so/v1/workspaces/{workspaceId}/wordmark

Path: workspaceId

Replace the workspace's wide logo (wordmark) from an image or a source URL. Pass file_content_base64 plus file_name, or source_url, not both. Images are PNG, JPEG, or WebP. The square icon is workspace operation replace-logo.

PUT /api/v1/workspaces/{workspaceId}/wordmark with Ken-Version 1.1.
Internal exposure. The backend requires a workspace admin.

The wide logo is what booking pages, External approvals and share
pages show first, falling back to the square icon. The response returns it
as wordmarkUrl next to logoUrl (the icon).

file_content_base64 is the image bytes in base64 and file_name its name;
they upload multipart field file (PNG, JPEG, or WebP, under 10 MB).
The hosted MCP refuses file_path, because it cannot read your machine;
off the hosted MCP, file_path opens only a file inside the MCP export
directory. source_url sends JSON sourceUrl instead. Provide exactly one
source. Response envelope: success plus the workspace resource.

resend

Write. POST https://api.ken.so/v1/invitations/{invitationId}/resend

Path: invitationId

Resend an invitation. The provider replaces it, so the id is new. Use the returned id for later get, delete, or resend calls.

POST /api/v1/invitations/{invitationId}/resend with Ken-Version 1.1
and X-Ken-Workspace-Id. Internal exposure.

The provider replaces the invitation, so data.id is a new provider id.
Pass the previous provider id (uinv_...) as invitation_id, as
members(operation="invitations-list") returns it. A numeric Kenso id
(public.user_invitation.id) is refused. Envelope: success plus data.

workspaces-transfer-ownership

Write. POST https://api.ken.so/v1/workspaces/{workspaceId}/transfer-ownership

Path: workspaceId

Body (json): memberId integer

Make another Admin the workspace owner. Only the current owner or Kenso staff. Off (not_found) without the permissions flag.

POST /api/v1/workspaces/{workspaceId}/transfer-ownership {memberId} with Ken-Version 1.1.
Internal exposure. X-Ken-Workspace-Id is the path workspace. member_id is the Kenso user id
of the new owner. While the flag is on, another admin demoting, restricting or removing
the owner (isOwner true on the member) is 409 owner_protected, so ownership moves first.
Callers: the owner, staff, or, when the workspace has no effective owner (none stored, or
the stored one is no longer an active Admin), a member with the members permission;
anyone else is 403 forbidden. A target who is not an active member here is not_found; one
off the Admin template is 409 invalid_state (members(operation="update", member_id=...,
role="admin") first). Naming Kenso staff is 403 (detail staff_member_protected) unless staff.
Naming the owner returns changed false. A concurrent change is 409 conflict: retry.
200: data has workspaceId, owner (member), previousOwner (when it changed from one) and
changed. Audited as workspace.owner_transferred.

update

Write. PATCH https://api.ken.so/v1/members/{memberId}

Path: memberId

Body (json): role string

Change a member's role. role is admin, member, view_only, client, or network_member. Requires a workspace admin.

PATCH /api/v1/members/{memberId} with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. The backend requires a
workspace admin.

role is admin, member, view_only, client, or network_member (refused with 400
until Network members are on). member_id is the Kenso user id.
A user the members list does not show is not_found, and nothing changes.
While the permissions flag is on, moving the workspace owner (isOwner
true) off admin is 409 owner_protected unless the caller is the owner or
Kenso staff: transfer ownership first with
members(operation="workspaces-transfer-ownership", ...).
Envelope: success plus data.

create_workspace_invitation

Write.

Link workspaces to Clerk organizations (staff) and invite by workspace id. Client-facing: create_workspace_invitation only.

Link workspaces to Clerk organizations and invite by workspace id.

Client-facing sub-surface (task 15 / D6): create_workspace_invitation, which
requires workspace admin. link_existing_client and link_unlinked_clients
remain operator/staff-only (superadmin on the backend).

The org-scoped Clerk invitation operations (create_invitation,
list_invitations, revoke_invitation, resend_invitation) are retired: they
needed a clerk_organization_id that Auth0-only workspaces never have. Use
members(operation="invitations-create"), members(operation="invitations-list"),
members(operation="invitations-delete") and members(operation="resend").

Organizations are the multi-tenant boundary inside Kenso. Each organization is
mirrored locally as a Client record with Postgres client_user as canonical
for memberships (Admin=1, Member=3, ViewOnly=4). The Auth0 organization is
the invite sidecar (metadata.ken_client_id), not the workspace switcher.
Kenso switches workspace in-app. Clerk created_by / org admin is the tenant
owner during dual-run, never Kenso staff.

Operations:
-----------
link_existing_client:
    Provision a Clerk organization for an EXISTING client and write its id
    onto the existing Client row in place. Idempotent (returns the existing
    link if the client is already linked). Restricted to Kenso super-admins.
    Requires owner_email or owner_clerk_user_id (the customer who owns the
    Clerk org). Staff JWT is never used as created_by.
    When Clerk refuses with quota_exceeded the API returns HTTP 503
    (errorCode=ServiceUnavailable, subcode=clerk_org_quota_exceeded).
    That is a per-user Clerk cap (typically 100 orgs created by the
    tenant owner), not a missing client. Ask Clerk support to raise
    the per-user organization limit; switching Kenso super-admin does
    not help because staff JWT is never created_by.
    Example: operation="link_existing_client", client_id=42,
             owner_email="founder@acme.com"
    Example: operation="link_existing_client", client_id=42, name="Acme Corp",
             owner_clerk_user_id="user_2abc"

link_unlinked_clients:
    Superadmin-only batch backfill: find clients with no Clerk organization
    and link each one (does NOT send invitations). Defaults to dry_run=True
    so the first call only reports candidates. Cap is 100 per call (backend
    MaxLimit); default limit is 50. Optional client_ids filters the batch.
    Per client, the owner is taken from Client.OwnerUserId (email / Clerk
    id). Kenso-staff owners are skipped with "owner identity required" - the
    caller JWT is never used as created_by. Dry-run reports intended
    ownerEmail without creating Clerk users.
    Staff/operator only - not available on client-facing connections.
    Example dry-run: operation="link_unlinked_clients"
    Example apply: operation="link_unlinked_clients", dry_run=False, limit=20
    Example filter: operation="link_unlinked_clients", dry_run=False,
                    client_ids=[42, 99], active_only=True

create_workspace_invitation:
    Invite by Kenso client/workspace id.
    Calls POST /api/v1/workspaces/{client_id}/invitations.
    Prefer this when you only know the workspace id. The workspace must be
    linked to a Clerk or an Auth0 organization; workspaces created since
    Auth0 replaced Clerk carry only an Auth0 org and invite normally. A
    workspace linked to neither returns 400. If the workspace has a Clerk
    org and the invitee is already its admin (the tenant owner), the
    backend returns success without sending a second invitation.
    Required: client_id, email. Optional: role ("admin", "member" default,
    "view_only", "client", or "network_member"; bare, spaced, or "org:admin" /
    "org:member" / "org:view_only" / "org:client" forms accepted,
    case-insensitive). Any other role is refused before the call. The tool
    sends the route's own role names (admin, editor for member, member for
    view_only, client, network_member), and the response echoes those names,
    which are the app's labels (Admin, Editor, Member, Client, Network member).
    The backend refuses network_member with 400 until Network members are on.
    Example: operation="create_workspace_invitation", client_id=1388,
             email="teammate@acme.com", role="org:admin"
    Example: operation="create_workspace_invitation", client_id=42,
             email="new@acme.com"

Parameters:
-----------
client : KenAPIClient
    API client instance
operation : str
    The operation to perform
name : str, optional
    Organization display name. Optional override for link_existing_client
    (defaults to the existing client name).
slug : str, optional
    URL-safe slug for the organization (optional for link_existing_client)
owner_email : str, optional
    Customer email who will own the Clerk org. Required for
    link_existing_client (unless owner_clerk_user_id is set). Clerk
    created_by is this owner, never Kenso staff.
owner_clerk_user_id : str, optional
    Alternative to owner_email when the Clerk user already exists.
owner_auth0_user_id : str, optional
    Additive dual-run owner id. Accepted now so callers can pass it, but
    not yet sent: backend Task 24 has not added ownerAuth0UserId to the
    vendored surface, and this repo's contract gate forbids payload keys
    the backend does not bind. Wire it as ownerAuth0UserId once 24 lands.
    Clerk owner fields are kept, never dropped.
client_id : int, optional
    Kenso client/workspace id. Required for link_existing_client and
    create_workspace_invitation.
email : str, optional
    Invitee email address (required for create_workspace_invitation)
role : str, optional
    Invitee role: "admin", "member" (default), "view_only", "client", or
    "network_member" (also "viewonly", "ViewOnly", "view only", "org:admin",
    "org:member", "org:view_only", "org:client", case-insensitive). Any other
    value raises a validation error. Sent as the route's role name: admin,
    editor (member), member (view_only), client, or network_member.
dry_run : bool, default=True
    link_unlinked_clients only: True reports candidates without calling Clerk;
    False performs the link. Default True for safety. The other operations
    have no preview and refuse dry_run=True.
limit : int, optional
    link_unlinked_clients only: max clients to process this call (default 50,
    backend-capped at 100).
active_only : bool, default=True
    link_unlinked_clients only: when True, only active non-deleted clients.
client_ids : list[int], optional
    link_unlinked_clients only: optional explicit client id filter.

Returns:
--------
dict
    API response: { "success": bool, "message": str, "data": ... }
    On Clerk organization quota exhaustion, KenAPIError with HTTP 503 and
    the backend message (subcode clerk_org_quota_exceeded).
    link_unlinked_clients data includes dryRun, candidateCount, processedCount,
    linkedCount, alreadyLinkedCount, failedCount, and results[].

invite

Write.

Invite users to Kenso by email. Client-facing op: invite (admin-only). Backend authz authoritative.

Client-facing sub-surface (task 15 / D6): invite only. invite needs the
members permission on the client-facing host.

### operation=invite
Invite a new user to the Kenso platform by email.

The invitation is stored in Kenso `user_invitation` and sent via the Auth0
org invitation sidecar. The invited user receives an email to set up their
account. Requires client management permissions. Legacy route, no role
field by design.

Requires `email` and `client_id`.
Example: operation="invite", email="newuser@company.com", client_id=42