# Kenso agent setup

You are an AI agent. The user wants you connected to **Kenso** (https://kenso.space/), where the HTML pages, prototypes, PDFs and images you make get reviewed: you push a file, people comment right on it, you read the comments back and push the next version to the same link.

Follow these steps. Keep the user informed in one or two short sentences per step, and ask before editing any file outside the current project.

## 1. Work out which agent you are

Claude Code, Codex, Cursor, Claude Desktop, or another MCP client. If you can't tell, ask the user.

## 2. Get the user's Kenso API key

Ask the user to create one at https://kenso.space/settings (they can sign up at https://kenso.space/signup first; the trial is free for 14 days) and paste it to you. Keys start with `kenso_`.

- Treat the key like a password. Never print it back in full, and never commit it to a repository.
- Below, `KENSO_KEY` means the key the user gave you.

## 3. Add the Kenso MCP server

Add it at the user level (available in every project), and merge with any existing MCP servers: never remove or overwrite the user's other entries. Back up a config file before editing it.

### Claude Code

Run:

```bash
claude mcp add --scope user --transport http kenso https://kenso.space/api/mcp --header "Authorization: Bearer KENSO_KEY"
```

### Codex

Codex reads the key from an environment variable, so the key never sits in the config file:

```bash
codex mcp add kenso --url https://kenso.space/api/mcp --bearer-token-env-var KENSO_API_KEY
```

Then, with the user's permission, add `export KENSO_API_KEY="KENSO_KEY"` to their shell profile (`~/.zshrc` or `~/.bashrc`). Codex must be started from a shell where that variable is set.

### Cursor

Add this entry under `mcpServers` in `~/.cursor/mcp.json` (create the file if it doesn't exist):

```json
"kenso": {
  "url": "https://kenso.space/api/mcp",
  "headers": { "Authorization": "Bearer KENSO_KEY" }
}
```

### Claude Desktop

Claude Desktop runs local commands, so it connects through `mcp-remote` (needs Node.js). Add this entry under `mcpServers` in `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\\Claude\\`):

```json
"kenso": {
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://kenso.space/api/mcp", "--header", "Authorization: Bearer ${KENSO_API_KEY}"],
  "env": { "KENSO_API_KEY": "KENSO_KEY" }
}
```

### Any other MCP client

Kenso speaks Streamable HTTP at `https://kenso.space/api/mcp` (and legacy SSE at `https://kenso.space/api/mcp/sse`). Every request needs the header `Authorization: Bearer KENSO_KEY`. Configure it the way your client supports remote servers with headers.

## 4. Reload

Tell the user if the client needs a restart or a new session for the Kenso tools to appear (Claude Desktop and Cursor usually do; Claude Code needs a new session).

## 5. Check it works

Once the tools are available, call `list_projects`. Then offer to push a tiny test page with `push_deliverable` and give the user the `review_url` to open.

## How to use Kenso afterwards

- `push_deliverable`: for small files (under about 40 KB), send `file` (base64, or raw text with `encoding: "utf8"`) or a public `url`, plus a `filename`. Returns a `review_url` to share and a `deliverable_id`.
- `start_upload`: for anything bigger, which is most real pages. Call it with the `filename` (and `deliverable_id` for a new version), then run the `curl` command it returns from your shell. The reply has the same `review_url` and `deliverable_id`. Never shrink, strip or split a file to make it fit, and never pass a Claude artifact or chat share link as `url`.
- `get_comments` with the `deliverable_id`: reviewers' comments, with where they were left and the screen and device they were left on.
- Every tool that takes a `deliverable_id` also accepts the review link (`https://kenso.space/r/…`), so you can work on files the user uploaded by hand. When the user names a file ("pull the comments on the pricing page"), find it with `list_deliverables`.
- Before editing a deliverable, find the local source. Call `get_file` for its `filename` and `sha256`, look for that file in the user's project, and compare (`shasum -a 256`):
  - **Same hash:** edit the local file.
  - **No local copy:** download `download_url` with `curl -o` into the current folder under a new name (never overwrite), and tell the user where it went.
  - **Local copy differs from the latest version, or several files could be it:** ask the user which one to work from before changing anything.
- To revise, push again (`push_deliverable` or `start_upload`) with the same `deliverable_id` and a short `version_note`. The new version lands on the same link and open comments carry over.
- `list_projects`, `list_deliverables` and `create_project` organise work; otherwise it goes to the user's Inbox.
- Accepted: HTML, PDF, PNG, JPG and SVG, up to 50 MB.

If anything fails, show the user the error and point them to https://kenso.space/setup or support@kenso.space.