Kenso MCP tools

MCP Servers mcp_servers

The workspace's own third-party MCP servers (Linear, Notion, Atlassian, Airtable or any https server) whose tools Ken and the other agents use. list, get and presets-list read them; create (no sign-in or OAuth, never a token), update, delete and refresh-tools change them. Needs the custom_mcp flag.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through mcp_servers_read and changes through mcp_servers_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: authorize, create, delete, get, presets-list, list, refresh-tools, update

authorize

Write. Early access: needs custom_mcp on for the workspace. POST https://api.ken.so/v1/mcp-servers/{mcpServerId}/authorizations

Path: mcpServerId

Start signing Kenso in to a workspace MCP server that uses OAuth; returns the URL to open. The member who called this opens authorizeUrl, signed in to Kenso, and approves (10 minutes).

POST /api/v1/mcp-servers/{mcpServerId}/authorizations. Sends Ken-Version 1.1. No body.
mcp_server_id: the server's id (a positive integer).
Returns authorizeUrl (the server's own sign-in page, with PKCE) and expiresAt (UTC). Give
the URL to the member whose credential made this call, to open in a browser where they
are signed in to Kenso: after they approve, the Kenso app stores the sign-in, lists the
server's tools and shows the result in Settings > Integrations > Agent tools. Anyone else
who opens it gets a state_mismatch refusal and nothing is stored. Nothing changes until
they approve. Needs the integrations permission (workspace admins).
Errors: 409 not_oauth (the server uses a token: set the token instead), 409
oauth_not_supported (the server offers no OAuth sign-in Kenso can use: connect it with a
token), 409 demo_workspace, 403 forbidden (the credential has no Kenso member), 503
service_unavailable (its sign-in cannot be reached or is not set up on Kenso: try again
later), not_found when the server is not in this workspace or the feature is off.

create

Write. Early access: needs custom_mcp on for the workspace. POST https://api.ken.so/v1/mcp-servers

Body (json): agents array, authKind string, description string, name string, presetKey string, token string, url string

Connect an MCP server that needs no sign-in or signs in with OAuth. Never with a token.

POST /api/v1/mcp-servers. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Needs the
Integrations permission (workspace admins). The request body is not logged: a URL can
carry a key in its query string.

auth_kind is none (Kenso checks the server at once and lists its tools, or saves it
with status error and a lastError) or oauth (the server waits as needs_auth until an
admin signs in from Settings > Integrations > Agent tools). Ken never handles
third-party tokens, so bearer-token servers are added only in Settings.

Send preset_key (from mcp_servers presets-list) or url (https, on the public internet).
name defaults to the preset's name and is required with a url. agents (ken, support,
studio-build, campaign-build; onboarding is accepted but never served) defaults to
those four. A workspace holds at most 100 servers: the 101st is 409 limit_reached.

delete

Write. Early access: needs custom_mcp on for the workspace. DELETE https://api.ken.so/v1/mcp-servers/{mcpServerId}

Path: mcpServerId

Remove a connected MCP server. Every agent loses its tools at once.

DELETE /api/v1/mcp-servers/{mcpServerId}. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Needs the Integrations permission (workspace admins). Erases the stored token or
sign-in, then removes the server. Returns 204. Confirm with the user first.

get

Read. Early access: needs custom_mcp on for the workspace. GET https://api.ken.so/v1/mcp-servers/{mcpServerId}

Path: mcpServerId

Read one connected MCP server with every tool and whether it is switched on.

GET /api/v1/mcp-servers/{mcpServerId}. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Read only. The server's fields are those of mcp_servers list; a tool an admin switched
off has enabled false.

presets-list

Read. Early access: needs custom_mcp on for the workspace. GET https://api.ken.so/v1/mcp-server-presets

List the MCP servers Kenso connects in one click (Linear, Notion, Atlassian, Airtable).

GET /api/v1/mcp-server-presets. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Read only.

Each preset has key, name, url, authKinds (the recommended one first), docsUrl and
logo. Pass key as preset_key to mcp_servers create.

list

Read. Early access: needs custom_mcp on for the workspace. GET https://api.ken.so/v1/mcp-servers

Query: agent string, status string

List the workspace's connected MCP servers and their tools.

GET /api/v1/mcp-servers. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Read only.

Oldest first, every server in one page (at most 100). Each server has id, name, slug,
connectionName (ws-{slug}), description, urlHost, authKind (none, bearer, oauth),
presetKey, status (connected, needs_auth, error), lastError, agents, tools (name,
title, description, readOnly, destructive, enabled), toolsRefreshedAt and createdAt.
Never the URL's path or query, and never a token.

agent (ken, support, onboarding, studio-build, campaign-build) keeps only the servers
that agent may use and only the tools it may see; it is empty for a caller who may not
chat with Ken. status filters by one or more statuses, comma-separated (OR).

refresh-tools

Write. Early access: needs custom_mcp on for the workspace. POST https://api.ken.so/v1/mcp-servers/{mcpServerId}/refresh-tools

Path: mcpServerId

Ask a connected MCP server for its tools again now.

POST /api/v1/mcp-servers/{mcpServerId}/refresh-tools. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Needs the Integrations permission (workspace admins). Takes up to
60 seconds and returns the server as saved afterwards; a server that fails is still a
success, with status error or needs_auth and a lastError to show the user.

update

Write. Early access: needs custom_mcp on for the workspace. PATCH https://api.ken.so/v1/mcp-servers/{mcpServerId}

Path: mcpServerId

Rename a connected MCP server, change its description or agents, or switch tools off.

PATCH /api/v1/mcp-servers/{mcpServerId}. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Needs the Integrations permission (workspace admins).

changes holds name, description (null clears it), agents (replaces the list) and
disabled_tools (the tool names to switch off, replacing the list; null switches every
tool back on). Absent fields stay unchanged. The URL and auth kind never change. Never
a token: a bearer server's token is replaced in Settings > Integrations > Agent tools.