---
title: "Kenso MCP Troubleshooting: Workspaces, Errors, Limits"
description: "Fix a Kenso MCP connection: pin a workspace with ?workspace=, what each 401 and tool error means, and the limits on requests and web reads."
path: /mcp/troubleshooting
family: mcp
updated: 2026-11-15
html: /mcp/troubleshooting
sources: []
facts:
  server_url: "https://mcp.ken.so/mcp"
  pin_a_workspace: "?workspace=<id>"
  auth: "OAuth sign-in, or an API key as a Bearer token"
  requests_at_once: "5 per API key or sign-in"
  web_reads: "100 calls a day"
---

# Kenso MCP Troubleshooting

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

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.

```text
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:

```bash
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 see | Cause | Fix |
| --- | --- | --- |
| 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.

```http
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.

## Related

- [Kenso MCP server](/mcp): What Kenso's MCP server does and every client it works with
- [Connect Kenso to Claude Code](/mcp/claude-code)
- [Connect Kenso to Cursor](/mcp/cursor)
- [Connect Kenso to n8n](/mcp/n8n)
- [Connect Kenso to Grok](/mcp/grok)
- [Kenso API reference](/docs): The same actions over REST

## Changelog

- 2026-11-15: Page published.
