Kenso

MCP

Kenso MCP Troubleshooting

Most Kenso MCP failures are a missing workspace, a skipped sign-in or a revoked API key. An API key that reaches several workspaces must name one: add ?workspace= and the workspace id to the server URL.

How Do You Pick a Workspace When You Have Several?

In short Add ?workspace=<id> to the server URL. An API key that reaches several workspaces needs it, and a sign-in can use it to stay in one workspace.

One connection to Kenso covers every workspace you can access. Signed in with OAuth, the agent names a workspace on each request, and Kenso runs it with your role in that workspace. A request that names none gets your list of workspaces back.

An API key cannot name a workspace per request. If the key reaches several workspaces, its connection must name one, or every call is refused with your workspace ids in the error.

The server URL pinned to workspace 42. Your workspace id is the number after app.ken.so/ in the app's address.
https://mcp.ken.so/mcp?workspace=42

A client that drops the query string can send the X-Ken-Workspace-Id header instead. In Claude Code:

claude mcp add --transport http kenso-acme https://mcp.ken.so/mcp --header "X-Ken-Workspace-Id: 42"

A pinned connection refuses requests for any other workspace. To work in several, add one connection per workspace, each under its own name.

What Does Each Kenso MCP Error Mean?

In short Each message below is what Kenso returns, with its cause and the fix.

Kenso MCP errors, their causes and fixes
What you seeCauseFix
401: Authentication required: no credential was sent.The client sent no Authorization: Bearer header. It skipped the Kenso sign-in, or the API key header is missing.Sign in to Kenso when the client asks, or send your Kenso API key as Authorization: Bearer.
401: Authentication required: Kenso did not recognise this Bearer token.The API key was revoked or mistyped, or the sign-in expired.Create a new key in the Kenso app under Settings > Integrations > API Keys, or remove Kenso from the client and sign in again.
This connection is not pinned to a workspace, and you belong to several.An API key that reaches several workspaces, on a connection that names none.Add ?workspace=<id> to the server URL, or send the X-Ken-Workspace-Id header, with one of the ids in the error.
You belong to several Kenso workspaces, and this call does not say which one to work in.You signed in, you belong to several workspaces, and the request named none.Tell the agent which workspace to work in. It takes the id from the list in the error.
client_id 43 is not permitted: this session is pinned to workspace 42.The connection names workspace 42, and the request asked for another one.Work in workspace 42, or connect with the plain server URL to reach every workspace.
Campaign 7 not found in workspace 42.Campaign 7 belongs to a different workspace from the one the request works in.Name the campaign's own workspace in the request, or use the connection for that workspace.
A call that names a campaign needs Campaigns view in workspace 42.Your role in that workspace cannot view campaigns, which Kenso checks before it touches one.Ask an admin of that workspace for Campaigns view.
Missing scope <scope>. Reconnect Kenso and allow: <scopes>Part of the Kenso approval screen was declined.Remove Kenso from the client, add it again and select Allow access.
Kenso could not link this sign-in to your Kenso account.The sign-in worked, but Kenso could not turn it into access to your account.Remove Kenso from the client and connect again.
Kenso worked, then asks you to sign in every time.The client's saved registration is gone, so Kenso rejects its refresh token.Remove Kenso and add it again, so the client registers itself again.
The sign-in page says you may have pressed the back button or opened too many login dialogs.The sign-in lost its state: several sign-in tabs were open, or third-party cookies are blocked for auth.ken.so.Close the extra sign-in tabs and connect again from one tab.

A 401 before you have signed in is normal: it is how the client learns where to sign in.

What Limits Does the Kenso MCP Server Have?

In short Five requests at once per API key or sign-in, the Kenso API's rate limits, and 100 web reads a day where web reads are on.

  • At most 5 requests per API key or sign-in run at the same time. More wait their turn instead of failing.
  • When the Kenso API rate-limits a request and its Retry-After is 60 seconds or less, the server waits that long and retries it for you.
  • A longer limit comes back as a tool error that names the limit and when to retry. Retrying sooner fails the same way.
  • Web reads (web_read, which maps a site or scrapes a page) are on only in some workspaces, at 100 calls a day.

How Do You Connect From a Script or a Workflow Tool?

In short Send your Kenso API key as a Bearer token, and add ?workspace=<id> when the key reaches several workspaces.

Create the key in the Kenso app under Settings > Integrations > API Keys.
POST https://mcp.ken.so/mcp?workspace=42
Authorization: Bearer <your Kenso API key>
Accept: application/json, text/event-stream

To label what a script changes, send X-Ken-Mcp-Client with the script's name. Kenso then shows the change as yours, made through that name. The header only labels your own calls and never grants access.

Free credits: 1,000 credits ($20) once, no card.

Changelog

  1. Page published.