# Kestroll setup

Kestroll is an AI video editor and media library. Every uploaded video is analyzed: transcript, speakers, people, scenes, and a moment-by-moment summary. Kestroll's MCP server, `https://api.kestroll.com/app/mcp`, lets you search footage by what's said or shown, edit compositions the user can open in Kestroll's editor, render and export videos, post to social accounts, and read post analytics.

To set it up, the user approves you in their browser, you get an API key, and you add the MCP server with that key.

## Rules

- Never print a key, a token response, a `device_code`, or an emailed sign-in link, and never put them in tracked files. The commands below keep them out of your output.
- Never run commands that print the environment (`env`, `printenv`, `ps e`).
- Configure only this client, at user level so it works in every project.
- If you can't run a step, give the user the exact command and wait.

## 1. Reuse a saved key

If `~/.kestroll/auth.json` exists, check its key:

```bash
KEY=$(grep -o '"access_token":"kest_[0-9a-f]*' ~/.kestroll/auth.json | cut -d'"' -f4)
curl -s -o /dev/null -w '%{http_code}\n' https://api.kestroll.com/app/mcp \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'
```

`200` means it works: skip to step 3.

## 2. Get a key

**Register.** Name the client after yourself and the machine. The name labels the key in the user's Settings → API Keys.

```bash
curl -s https://api.kestroll.com/oauth/register -H 'Content-Type: application/json' \
  -d '{"client_name": "Claude Code (work laptop)"}'
```

**Start sign-in** with the `client_id` from the response. `login_hint` is optional: pass the user's email if you already know it.

```bash
curl -s https://api.kestroll.com/oauth/device_authorization \
  -d client_id="$CLIENT_ID" -d login_hint=user@example.com
```

Keep `device_code`, `user_code`, and `verification_uri_complete` from the response. A `429` means too many requests from this network: tell the user instead of retrying.

**Open the link** in the user's browser:

```bash
open "$VERIFICATION_URI_COMPLETE" 2>/dev/null || xdg-open "$VERIFICATION_URI_COMPLETE" >/dev/null 2>&1
```

Then send the user this message with the real values, unshortened. On a remote machine no browser opens, and Kestroll never emails the code, so they need it:

---

**Connect Kestroll in your browser**

1. A browser window should have opened to this link. If it didn't, open it yourself:

   ```
   {verification_uri_complete}
   ```

2. Sign in, or create an account if you're new.
3. Check that the page shows this code, then click **Approve**:

   ```
   {user_code}
   ```

The link expires in 10 minutes.

---

**Wait for approval.** Set `CLIENT_ID` and `DEVICE_CODE`, then run this. It polls for up to 10 minutes, so give it a long timeout or run it in the background. On approval it saves the token response to `~/.kestroll/auth.json`, readable only by the user, and prints `approved`.

```bash
mkdir -p ~/.kestroll && chmod 700 ~/.kestroll
RESULT=timed_out
for _ in $(seq 120); do
  RESPONSE=$(curl -s --max-time 30 https://api.kestroll.com/oauth/token \
    -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
    -d client_id="$CLIENT_ID" -d device_code="$DEVICE_CODE")
  if printf '%s' "$RESPONSE" | grep -q 'kest_'; then
    (umask 077 && printf '%s' "$RESPONSE" > ~/.kestroll/auth.json); RESULT=approved; break
  fi
  ERROR=$(printf '%s' "$RESPONSE" | grep -oE 'authorization_pending|slow_down|access_denied|expired_token|invalid_grant')
  case "$ERROR" in
    authorization_pending|"") sleep 5 ;;
    slow_down) sleep 10 ;;
    *) RESULT=$ERROR; break ;;
  esac
done
echo "$RESULT"
```

| Result | Meaning |
| - | - |
| `approved` | The key is saved. |
| `timed_out` | No answer in about 10 minutes. Tell the user. |
| `access_denied` | The user clicked Deny. Stop. |
| `expired_token` | The link expired. Start again only if the user agrees. |
| `invalid_grant` | The `device_code` is wrong or already used. Start again. |

The token response names the account (`user.email`, `organization.name`): tell the user which one you connected.

**Other ways to get a key:**

- **Your own inbox.** `POST https://api.kestroll.com/auth/magic_link` with `{"email": "…"}`. Copy the "Sign In to Kestroll" link from the email without opening it (opening uses it up), then `POST https://api.kestroll.com/oauth/accounts/verify` with `{"email": "…", "name": "<key label>", "confirmation_url": "<link>"}` and save the response to `~/.kestroll/auth.json`.
- **From the user.** An organization owner creates a key in Settings → API Keys and saves it to `~/.kestroll/auth.json` as `{"access_token":"kest_…"}`.

## 3. Add the MCP server

If a server named `kestroll` is already configured, replace it. Each command reads the key from `~/.kestroll/auth.json`.

**Claude Code**

```bash
KEY=$(grep -o '"access_token":"kest_[0-9a-f]*' ~/.kestroll/auth.json | cut -d'"' -f4)
claude mcp remove --scope user kestroll >/dev/null 2>&1
claude mcp add --transport http --scope user kestroll https://api.kestroll.com/app/mcp \
  --header "Authorization: Bearer $KEY"
```

**Codex**

```bash
KEY=$(grep -o '"access_token":"kest_[0-9a-f]*' ~/.kestroll/auth.json | cut -d'"' -f4)
codex mcp remove kestroll >/dev/null 2>&1
printf '\n[mcp_servers.kestroll]\nurl = "https://api.kestroll.com/app/mcp"\nhttp_headers = { Authorization = "Bearer %s" }\n' "$KEY" >> ~/.codex/config.toml
```

**Cursor:** add this to `~/.cursor/mcp.json`, keeping other servers, with a command that fills in the key:

```json
{"mcpServers": {"kestroll": {"url": "https://api.kestroll.com/app/mcp", "headers": {"Authorization": "Bearer <key>"}}}}
```

**Other clients:** a remote Streamable HTTP server named `kestroll` at `https://api.kestroll.com/app/mcp` with the header `Authorization: Bearer <key>`.

## 4. Restart and verify

Clients load MCP servers at startup. Ask the user to restart you (for Claude Code, `claude --continue` keeps this conversation). Then call the `filesystem` tool with `{"action": "list_folders"}`; a real result confirms the connection. Tool names may have a client prefix such as `mcp__kestroll__`.

## 5. Hand off

Tell the user what you configured and which files you changed. Then offer a first task:

- To add footage, they can upload it at https://app.kestroll.com, or hand you files or links: you upload files from this machine with `file_transfers` and import links with `web_fetch`.
- Once it's processed: "Find the best 30-second moment in my latest video and cut it as a vertical clip with captions."